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GETTIlUC 

STARTED 


Copyright 2003 hy Dam Mark 


Getting Started; 
More on Xcode 


I must say, 1 am really enjoying digging inU> Xcxxle, I’m 
impressed with what I’ve sain so hir. I’he l>ugs I've encountered 
I lave mostly l>een cosmetic and, I assume, e^isily ftxable. My 
understanding is that the WWUC rele:tsc Is the only Jaguar 
release and that all fixes and future releases wall lx? Panther-only, 
For the moment, HI stick with the Jaguar version. As smn 
as a “for puhlic consumption" version of the Panther Xcode 
makes its way into my htit little liands, I'll shift permanently into 
Panther nKxle. 


Go ahead and select Butid and Dehtt^ from the drop¬ 
down menuH Xcode will build and launch a debug-ready 
version of Skeicb and open the debugger window. As you’d 
expect, the debugging window allows you to control the 
debugging process, 

n.se the D(Kk to bring Sketch to the front. Click on the 
rectangles icon in the palette, then click and drag out a rectangle 
in the main window (see Figure 2). Note that the rectangle that 
appears is not filled. 


EonoR Window Details 

last month’s column slatted oFf^ hy opening an existing 
Project Builder project called Skeichphxfnvj in Xcode and 
updating the target, creating a new target called Sketch 
(UpgradeL Go ahead and launch Xcode and open the project. If 
you are starting from scratch, you'll hnd Skdch.pbxproj in the 
directory /IMK*lo/Kr/Fxumples/AppKit/SkKd^^^ Remember, you 
can open a project liy navigating to the right direciory and 
cHeking the Ofxnt button. Xcode wall find the prrjject file for you, 
Wlien tlie prxjjett window' appears, click and hold on ihe Build 
atid Debug iam. After a slight patise, n drop-down imniu will apjx“jr 
(see Figure 1), 'the little triangle to tlie k>wer right of an Xccxle Xmi 
icon Ls your due that tlieie's a drop<lQwn menu lurking within. Just 
remember to hold and wail a hitch fex ilie menu to apjx^n 



_ 15 Sketch _ 

O 


^^^Build and Debug 


Build and Run f- 

^ Run ^ 

4 Debug 


nit Marne ^ 
0 AppKlt.fnii 

[ Arrow, tiff 
I Circle^tiff 
i Cocoairani 


figure 1. The Build and Debug drop-doum men it. 


Figure 2 Dragging out a rectangle mtb Sketch, 

Nt)w go back to the project window and click on the Project 
Symbols group (the Iasi gnnip in the Groups & Files column). As 
you .siiw last month, this ‘"smart group" fisis all the symix>ls in the 
fproject. Type mtl in the search field to reduce the list of symbols 
(See Figure 5X 


Dave Mark b a long-lime Mat: devek>|Xfr and MticTcch contfibutor. Author of more than a dozen hooks on various Mac-tlovdopmeni topics, Dave is 
all about Xccxle tliese days. Uisi monili's column focused on the l>asics of opening a Project Builder project, uirgei a>nversion, and the pmjeti window 
user interface. This month's instaHment will fcx!us on tire editor interface and a demo of fix-and-coniinue. 
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figure X Using the search Jieid to Jttui the init method in 
SK7Tjraphic,m. 


We’re looking for the init nieth(MJ in the file SKlXjraphic.m. 
TIiltc arc I wo way.s to open tJiis file from the Itsiing in ilie 
Project SymboLs gn)up. We can click on the Uditor icon in the 
toolbar (the cursor Is pointing to this icon in Figure 3) to open 
an editing pane for that file in the Project Window. Alternatively* 
we on doLibie-cIick on ilie line listing the file we want to open 
that Ilie in a separate editing window. Thafs the method we’re 
going to use here. 

Figure 4 shows the editor window that appeared wlien I 
doul>le-clicked on SICfGraphic.m. At the top of the window is 
the editor texilbar. Just fieneatli that is the status bar (in Figure 
4 it says Sketch (Uiygraded)). 


l?elow the status bar is the navigation bar. Towards the left 
edge of the nav bar is a pair of arrows. 'I'hese act like tlic left 
and riglit arrows in your l)rowser and are used to move between 
source files. You 11 see liow this works in a sec. 

If you scan kj ihe right side of the nav bar, you1l see an 
icon showing a pair of overlapping rectangles, a grey one in 
front of a white one. This is called the counterpart icon. 
Click on it to switch betw^een a .m and its corresponding .h 
file. For example, dick the counterpart icon to switch to 
SfCrciraphic.h. Note that the left arrow on the left side of the 
nav bar is now enal)lecl. You can dick it to go back to the 
file SKTGraphic.m. And, as you'd expect, once you dick on 
llte left arrow, the rigltt arrow will be enabled .so you can go 
back to SKTGraphic.h, As promised, just like the arrows in 
your browser. 

As you visit different files in your editor window, they are 
added to a list, sort of a running history, Imniediaidy to the 
right of the arrows in your nav i)ar is a popup listing all the files 
in tiiis history list. Select a file name and the editor edits that 
file. Makes sense. The liny dogear icon immediately to die left 
of the file name is a dirty flag. If die file is dirty (if it has 
changed since the last save) the icon is grey. Save the file and 
it returns to wliiie. 

Just to the right of die file name is a cokin (*":**) followed by 
the current line number (either the beginning of a selection, or 
the line holding die insertion point). If you want to go to a 
specific line in a file, you can irial and error it, clicking araund 
using tlie line numlier in the nav Ixir to help you home in on 
the right line. Or you cun select Go to Line,,, from die Find 
menu iC'ommcitui-L) and use that interface to select a specific 
line or range of lines (See Figure 
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Figure 4, A new editing whuioui listing the fiie SlCFGmphic,m. 
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O Character 
- 5:7 
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figure 5. Ihe (7o to Line,., command from the Fittd merm. 

Also in the nav bar, just to the right of the file popup menu, 
lies tile foncdon/mciliod popup. As you'd expect, this j^opup 
lists all the functions in die current file. Click anywhere instde a 
function and that function is shown in liie iK?pup title. Click on 
the [X)pup and all die funaions/methods in the file are listed in 
the order in which they apptur. Opdon-click and the functions 
are listed in alphabetical order, separated by implementation. 
Give it a try. You’ll get it right away. 
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Nexi over m [he right is the counterpuri icon (which we 
tJiscu.sscd above) followed immediaicly by llie included files 
pt)piip (it looks like a #) wliidi lets you edit the tree of included 
files. Figure 6 siiows the included files popup for fiKTCrapbic.m. 


SKTCraphicView.h 
SKTDrawDocu ment. h 
SKTFoundatlonExtras.h 
SKTCraphic.h 



✓tSKTCraphicm 


Figure 6. The inciudedJiies popup menu. 


Fetch 


To the lower right of die included files pcjpup (at the top of 
the scroll bar) is die 4^iit vieu? toggle. Click on the toggle to 
create a split in the editing window. Click the toggle again to 
remove the split. Once you create a split, the spiit resize control 
appears toween the upper and lower scroll Irars. To move the 
spill, just drag this control (See Figure 7). Note that in the 
current Jaguar release (and presijnia!>ly the c>w/v Jaguar release) 
of Xcode, the split resize control does niji get drawn when you 
first create a split, JiLst resize the window a tiny bit and the 
control w ill appear. 


0 0 Q§ SKTCraphic.m^3 


Build 
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Sketch (Upgraded) 

^ ► ]4SKTCraplitc,m:iQ t <No selected i % 

•import “SKTFouniptionExtroe^h^ 

NSString *SKTGrciphiol>iclChangeNotif icotiw = 
^’‘SICTGraphlcDidCiwge" ; 

^implementotton SKTGraphtc 


^ l*I SKTCraphic.m:10 : <No MtCCted $' & 

ttnport "SKTCraphic.h" 

•import "SKTCrqphicVtev.h" 

•import "SKTDrawDocwftcnt.h" 

•import "SKTFoundotioniExtrqs.h* 



NSString ^^TGrc^rfiicOidClwgaMotif Icotlon « 
^"SKTGraptncGitiChcrnge" ; 

Qimptementotton SKTGrqshic 
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Mac’s best friend. 
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Figure Z Dragging the spiit resize controL 


Version 4.0.3 now available. 
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Fix and Coatinue 

One of my favt>rite Xcode features Is Fix-and-Conltniie. 
With Mac OS X's built-in support for dynamic linking, you can 
actually your code while it is ninnmg and watch liie 

change come to life. Really. 

So let's try this out. When you played with Sketch earlier 
in the column, you dragged out a rectangle and saw that the 
result was unfilled- If you look through the source code, 
you 11 find that the fill color is white, bur the setDrawFill: 
method is called with the parameter NO. In SKTGraphic.m, 
here’s the init jnethod: 


- Cldjinlt f 

Jielf - [super init) : 
if (seif) { 

^document " nil: 

[self setBoundfiiNSMakeRect(0.0, 0.0. 1.0, i.O)]; 
[self SfttyillColnr:[KSColor whiteCdlnr]]; 

Iself setOrawsFilliNOl: 

{self setStrokeCoior:[NSColor bInckColorJ]: 

[self setDrawsStroke:YES]: 

[self setStrokeLlrveWidth: 1.0]; 

_origBounds - KSZeroRcct: 
_gFlags.!BanipulatJn6Bounds ~ NO; 

return self: 

) 


Pay special attention to lines 6 and 7, which correspond 
to lines 20 and 21 in the file. If you haven’t already, launch 
Sketch in the debtigger. You can click on tlie Debug spray 
can in the editing window or debug window’s toolbar, or 
select from the hammer/spraycan icon in the Project 
Window’s toolbar. 

Once Sketch launches in debug mode (you can tell the 
debugger is active because the Terrmrmte and Fame icons will 
Itc enabled in ihe Ik^bug window), drag our a couple of 
rectangles, just to prove iliai they are, indeed, unfilled. 

Ntjw go back to your editing window for SKTGmphicjn 
and change line 20 and 21 frt>m: 

(self setFillCblor:tNSColor whiteColorl1; 

[self £etDrawGFli!:NOj; 


to: 


[self setFlllColor;INSColor greenColor]]; 

[sell setarawsFilliYES] : 

Do iVOrsave. You 11 see why in a sec. 

Basically, we’ve changed the fill color from white to green 
and weVe told sketch thal we da want our shapes filled. 

Ntjw cromes the cool part. 

Select Fix from the Dehug menu. 

Remenil^er not to save! 

You’ll see a message in the Delmg window' about compiling 
and building. Om^ that settles down, go Ixick to the running 
Sketch and click and drag out a rectangle. Wait, IVe done it for 
you. Check out Figure 8. As you were expecting, the reaangles 
are now filled and green. 
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Figure fk After ihe fix is applied, our reels are 
filled unth green. Coolf 

Once you are done playrng wiLh yi>ur new green rects, quit 
Sketch and rerun it, eillier as a straight ntn or via the debugger 
Notice diat your rectangles are hack to being unfilled (you did 
remember to noi sxive your changes, rigliL^) To me, this is a 
beautiful way to play witii your code. You can make changes, 
experiment, use Dehug/Fix to test out your cfianges, see what 
works for you, then save what you want to. 

1 find dynamic linking taseinating. Fix and Conciniie works 
for Oi>jec:tive C, Carlxjn/C++ or even stmighi (', so it's available 
to all Mac OS X APIs and development languages. Though the 
Xcode team did not ere^ale dynamic linking, they did an 
excellent joli rolling it into the environment. Rrilliand 

You may have noticed a scotclvtape dispenser icon in the 
Dehug window with the label Fix. Clicking this icon docs 
die same tiling as selecting Fbc from die Debug menu. 
There is a bug (1 Ixrlieve it is fixed in the current Panther 
release) wliere the icon Is disabled (it just lieeps wlien 
you click it). Fortunately, the bug dties not affect the Fix 
item in the Debug menu. 


Tnx Next Month.,. 

Whelp, I’m out of space again. <sigh>. There’s so much 
more 1 want to talk about. Next month, weTe going to take the 
debugger through its paces and well also play around with a 
feature called code completion, one of my very favorite parts of 
Xcode. See you then...© 
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SECTION 7 


By Rich Morin 

Time-based Daemons 


at(1X hatch(1X cron(1X etc. 


Most daemons Ci,e., !>ackgrc>und pnx:esses) ;ire event-based, 
responding to an incoming packet, the appearance of a file, etc. 
Some daemons are time-based, however, occurring at a given 
time (or times). 

BSD (and therel>y OSX) makes it very easy to set up time- 
based daemons. In fact, there are several way,s to do this, 
depending on your needs. Let's look at some of the options. 

CRON 

The cron(8) subsystem (see also crontab(1,5)) runs 
commands at times which are specified in one or more control 
files.. It is also, as describetl the l>asis for lime-based 

seivices such as at(1) and period ic(8). 

Note: The command “man cron” fails in Mat' OS X 10.2.6, 
i)ui you can view the man page by typing “more 
/usr/shar6/man/cat8/cron.8.gz”. 

Originally, there was only one crontab(8) file, located at 
/etc/crontab. This file was only editable by root, ihougli it could 
nm commands as other ii.sers. Later, individual users were 
given the ability to imiintain their own ctmirol files, using the 
crontab(l) command- 

The default version of /etc/crontab on Mat‘ OS X ltx)ks like: 

# /etc/croniab 
SHELL=/bin/sh 

PATH-/etc:/bin;/sbin:/usr/bln;/usr/sbin 
IJOKEWvsr/ log 

# 

hour mday month wday who command 

// 

#*/5 * • * root /usr/libexec/atruti 

H! Run dally/weekly/monthly jobs. 

15 3 * * • root periodic dally 

30 4 ' * 6 root periCHilic weekly 

30 5 1 * * root periodic monthly 

Bnvironmeni variables can l>e set (using Bourne shell 
syntax) for the scheduled commands. Thus, the commands listed 
in this file will have HOME, PATH, and SHELL set for diem. Ik: 


sure to Lake these set!ing.s into account when writing scripts to 
be nin under cron; if your script a.sks for a command that isn’t 
found on the PATH, for example, it wt>iTt act as desired. 

As in die case of mast ESD a^ntiol files (and many scripting 
languages), can lx: used to indicute the start of a commenL 
extending ilirotigji the end of the current line. TtiLs is often used to 
disiilile schcsJuling lines (such as the one for “atrun", in diLs example). 

Each scheduling line luis three parts, separated by white 
space. The fli-st pint may be a special string (e.g,, ©rnboot, 
©daily), but more commonly ii will l)e a set of five fields, also 
separated by white space. The seermd part is the username (e.g., 
root) under w^hich the command will be run. TJie third part is the 
command (e.g., "periodic daily''). 

in the example, "periodic daily ' is sc:hediiled to he mn (as 
root) at 3:15 AM every day. Similarly, “periodic weekly' and 
“periodic monthly" are st hecluled for 4:30 AM each Salurtiay and 
5:30 AM on the firsl day of each month, respectively. 

'llie format of crontab files for individual users is almost 
idenlicai to that for /etc/crontab, The only difierence is that the 
""who” (username) field is not present, 'I'his makes sense; only 
the rof>[ account is able to set the user id under which a 
command will lie run. 

Although /etc/crontab can lie edited in any desired manner, 
the individual crontab files must be edited by means of the 
crontab(l) command. I'his prevents race coiKlititnis, ensures that 
the cron daemon will notice any changes, etc. 

PFRlOniC 

If you have a system maimenance command that needs to 
lx‘ nm during olT hours on a daily, weekly, or monthly basis, the 
periodic' siibsystem {periodic(8), periodic.conf(5)) may Ix' exactly 
what you want. 

Ihe periodic(8) command i.s actually a shell si’ript. I won't 
discu.ss it here, but you m;iy wish to give it a l(K>k: '"more 
/usr/sbin/periodic”. Basically, however, the script runs every 
executable file found in the sjiccified dirtx'Kiry. For example, 
“peritKiic daily” runs any commands found in /etc/periodic/daily: 

% wc -1 /etc/periodic/daily/* 

56 /etc/periodic/daily/I00.clean'logs 


Rich Morin has been using computers since 1970, Unix since 198.3* and Mac-lxiscd Unix since 19H6 (when he helped Apple t:rejle A/UX 1.0). When 
he isnT writing this column, Rich runs Prime Tinu' Freeware (WWW.ptf.COm), a publisher of liooks and CD-ROMs kw tlie Free and Open Stjurc'c softw^are 
community. Feel free to write to Rich at rcini@ptf.C0m, 
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131 /c lc/peri<?dlc/daily/SOO, daily 
18? total 

1 wouldn't suggest tnodifying any of these files, as Apple 
may overwrite them in an update, but putting in your own Hies 
should Ik* fairly safe. Just stuff an executable file into the 
appropriate subdirectoty, picking the filename to sort into the 
dcsirtd exeaition order: I’or example, if you liave a script that 
needs lo mn after "500.daily”, you could name it xsometiung like 
"eoOJocal.foosciipr. 

You may enjoy looking through these riles to see what 
gets done while you're off snoozing: try "more /etc/periodic/7*”. 
'I'he configuration riles, descrilied in periodic.conf{5), are also 
worth a look. 

At, Batcti, etc. 

The at{1) and batch(l) commands act in a very similar 
manner lo cutrh other* Both commands schedule a rile for 
execution at a specified time. Tlie difference is that batch(1) also 
checks the system load level, ensuring ihal llie cominand doesn't 
add work to an a I ready-overloaded system* 

In order to use cither command, however, you 11 have to 
imcommeni tlie ' atrun'' line in /etc/crontab, ousing the program 
to l)e run every rive tninutes: 

75 * * * ‘ rear /usr/iibexec/atnin 

Actually, Lhere's no particular reason wliy you couldnl 
schedule atrun to run every minute, if you wish. On a desktop 
machine, an occasional process start-up is unlikely to make a 
noticeal)le difference. IV) try this, just edit the line to; 

* - * * * /usr/libex^c/atrun 

Note: The docunientaiion and conrigumtion of at{1) in OSX 
10J.6 are a bit deficient. Although the at(1) man page says that 
‘"Traditional access control to at and batch via the files 
/var/at/at.allow and /var/at/at.deny is not implemented”, the 
program will fail unless (at least) one of these files is present* 
Tile spcx>l directory (/var/at/spool) may also rnLssing, causing 
scheduled jobs to silently faik Foriunaiely, the fixes are simple: 

% SM 

Password: 

tf touch /var/at/at.deny 
// mkdlr /var/at/spool 
3? exit 
exit 

% 

Having worked our way past the setup liassles, Icfs try 
ainning some at(1) jo))s* Here's a sliort test script we can use: 

# m - aift) icsi script 

(date: print&nv | sort) > att.$$.out 


For llie shell<halleage<!, here's a rundown of what's going 
on here, llie initial colon tells the kernel lliat the script should 
lx interpreted by the Bourne shell* llie real w^ork i,s done by a 
single line which slartHS up a subsheil (subsidiary copy of tlie 
shell), has it nm "date” and “printenv I sort ', and redirects the 
(concatenated) out pur into a file. 

Beaiuse “$$” evaluates to the process ID of the interpreting 
shell, the name of the file will Itwik sfimething like 
“att*12345,out". After you have edited the rile, make it executable, 
run it, and examine ihc results: 

% chmod +x; att 
% att 

% more att,*,out 

Fri Jul h 18:46:38 PDT 2003 

HOME=/Uaets/rdiii 

PATH=/Users/ rdai/bln:, *. 

PWP-/Dse^s/rdiii/, *, 

SFntT*Wbiii/tcsh 

The outfiLil show.s us the date and time that the cormnand 
was run, as well as the settings for any environment variables. 
Now', let's try sc^heduling the script via at(1)^ waiting for it to 
get Rin, and comparing the output with that of our first 
(manual) run: 

% at -f att +1 ninute 

Job a010ce73c.0Q0 will be executed using /bln/sh 
% atq 

Date Owner Queue Job# 

19:04:00 07/04/03 rdm a u010ce73c.000 

\ stq 

It _a_c_t_._*_,*^o_u_t_ 

_4_ J_9_:_0^0. : 4^8^ _P_D_T_ _2_0_0_3_ 

IC _l_9_:^0_5_:_0^0^ *.P_D_T_ _2_D_0_3^ 

_Z_3_._2,5,c^2.3. 

-<- _T E ,R_M_=_v^t_l_0^£)_ 

Not too iiJtiny clianges, really. The time changed, of course, 
bill most of the environment variables suiycd the same. SHLVL 
(die slieU level) is lower for the at(1) run, Ixcause no interactive 
shell was involved. The TERM and TERMCAP variables aren't *set 
for the at{1) run, hecau.se no temiinal i.s attached to the process. 

RoUJNt; YOtJR OWN 

If none of these facilities is quite what you need, consider 
creating your own time-based daemon* Simply putting a 
prcKCSS to sleep for a specified pericxi is quite simple; making 
a process wake up at a sy^ecified time is a bit trickier, hut .still 
quite po.ssib)e. 

If you take this approach, however, you may want to IcKik at 
the source code for existing routines tliat perform similar services* 
The Darwin source code (www.openciarvvin.org) lias the source code 
for the commands de.scTibed in this column* Tlic CPAN 
(epan pedorg) is a good place to Icxik for relevant Peri mcxlules* 


14 


Time-based Daemons 


MAffl'ECH • Seftemher 2003 












Complete Sourte Control 
and Do fort Management 

Mat 05 X 


chdiigiit^ ths world 

of software detelopment 


Effective source code control and defect tracking require powerful, 
flexible,and easy-to-use tools—Surround SCM andTestTrack Pro 


‘ Complete source code control with private 
workspaces,automatic merging, role-based 
security, and more 

■ Comprehensive defect management — track 
bug reports and change requests, define 
workflow, customize fields 

’ Fast and secure remote access to your source 
files and defects —work from anywhere 

• Advanced branching simplifies managing' 
multiple versions of your products 


■ Link code changes with defects and change 
requests — know who changed what, wheri, 
and why 

• Scalable and reliable cross-platform, 

, client/server solutions support Mac OS X, 
Windows,Linux,andSolaris - 

• Exchange data using XML and ODBC, extend 
and automate with SOAP support 

• Licenses priced to fit you r budget 


Seapine Software Product Lifecycle Management 
Award winning, easy-to-use software development tools 


i'UittiJiit 

Surround SCM 
TestTrock 

PRO 


^softwane ^ 
dSveLopment 

nthttnnual 
product 
OKEOllGhCp 
.•warn 


oil product nufnes M fierein are registered trodemerks of their respective owners. Al rights resend. 


Download Surround SCM 
and TestTrack Pro at 
www.seapine.com 
or call 1-888-683-6456 







































By Michael R. Harvey, Reviews Columnist 


JuiceTO 


Portable power for most mobile needs 


lociay we talk about juice, 1 here's all kinds. Orange 
juice, grape juice, cranberry juice, and my .soas favorite, the 
ubiquitous juice box. But that's not important right now. Tlic 
Juice we have before us today is a highly adaptable and 
expandable power supply. The Juice70, from iGo Mobility 
Products, is an adapter that can be used with most laptops, 
Apple, and PC. The basic package comes with the main 
power brick, an interchangeable power cord for 110 outlets, 
as well as one that plugs into i>oih auto power outlets and 
power outlets found in airline seats. On the other end of the 
pow'er brick is the cord that plugs into your compviter. For 
this side, several tips are provided that fit to most la[)U)p 
computers, as well as a chan to help you determme which 
goes into which. Be careful not ro lose the card, as some 
adapters can fit into the wrong laptop, poieniialiy cau,sing 
damage. A carrying case (of fair quality) is included ro hold 
all this stuff. That is not all, though. 

Part of wlmt makes the Juice70 different form other third 
party adapters is what iGo terms the "Peripheral Powering 
System.” On the cord from the power brick to the computer 
is a small port. Into this port, you can plug any of a number 
of adapters (all of which are sold separately) for cell phones, 
Nokia, Kyocera, and others, and PDAs from the likes of Sony, 
Compaq, and others. The compatibility chart for these can he 
found on the iGo web site. 

This is really one great product, 'Fhe only knock is 
against it is the cords. They can gel unwieldy at limes. If 
they had some better way to be controlled, belter than the 
included Velcro straps anyway, or were retractable, that 
would make this product near perfect. Tlie Juice70 is $119.95 
directly from iGo. Add on charging cables for PDAs and cell 
phones cost $19.99 each. This is good way to give yourself 
that extra charger you alw'ays seem to need. 

wwwjgo.com 
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by Paul Ammann 


Moving C and C++ Code to Java 


Even though Java is caLclung on pretty rapidly as a 
powerful new language with a lot of potential, there is a 
significant problem in dealing with the large existing C and 
C+-t- code base. As a Java program men have two 
solutions to this problem: convert yt>iir existing C/C++ code 
to java or interface your Java code to the C/C++ code, 
Althougli the latter solution is certainly a viable upturn, 
especially in terms of dcveiopment resources, this article 
focuses on the former If youVe really bent on keeping your 
C/C++ code as it is, 1 w'ill cover this topic in my next article, 
"Interfacing to Existing C and C++ Libraries/ 

The prospect of moving C/C++ code to Java might seem 
somewhat daunting at first, liowever, the similarities in 
syntax between the languages alone makes matters a little 
easier to handle. In reality, you can isolale the differences 
between the languages and form a strategy aimed at fixing 
trouble spots in the code. 

J'his article takes on die challenge of converting C/C++ axle 
to Java code an mm at a time. You learn not t>nly how to 
convert C/C++ ccxle to Java, but also why Java is different and 
requires the changes in the first place. If you are following along 
attempting to port your own ccxie, to make incremenral 
changes as you cover each section. You'll probably find that the 
task isn’t as bad as you originally thought. With that in mind, let’s 
get started! 

FiiJ* Organization 

Before you even liegin changing any source code, ids 
iiTiIKirtant to undersrantl a fundamental difference betw^een 
source files in Java and C/C++, In C and C++, must source files 
come in pairs consisting of a heailer file (,h) and an 
implementation file (x or .cppY The purpose of this file 
structure is to separate the declarations of tlie functions and 
classes from the definitions. This enables other programmers to 
understand code by view'ing header files, while keeping them 
out of the specific implementation details found in the 
implementation files. 

In Java, there is only one source file (.java) per logical 
code structure. Java classes contain class declaration 


infcjrmaiion that can be easily extracted using the javap class 
file disasscmldcT tool that comes with the JUK. Because of 
this, there is no need to maintain a header file with class 
declaration information. All the code for a Java class goes in 
the Java source file. 

Vt hat does this mc^an to you? Well, it means you should get 
ready to merge all your header and implementation files into 
Java files. Once youVe done that, you can move into mcxlifying 
tile code itself. 

The Preprocessor 

Ail C/C++ compilers implement a stage of compilation 
known as the preprocessor. Tlie C++ preprocessor basically 
[K-rfonns an intelligent search and replace on identifiers that 
have Ijeen declared using the #define directive or typedef. 
Akhoiigh most advocators o\ C++ discourage the use of the 
preprcxessor, which was inlierited from C, it is still widely used 
by most C++ programmers. Most of the processor definitions in 
C++ are stored in header files, which complement the actual 
source code (impiementation) files. 

Tlie problem with the preprocessor approach is that it 
provides an easy way for programmers inadvertently to add 
unnecessary complexity to a program. Many programmers 
using #define and typedef end up inventing their own 
sublanguage within the amfines of a particular project. This 
results in other prognunmers having to go through the header 
files and sort out all the ^define and typedef information to 
understand a program, which makes code maintenance and 
reuse almost impossible. An additional problem with the 
preprocessor approach is that il is very weak when it comes 
to type checking and validation, 

Java does not have a preproce.ssor, It provides similar 
functionality (#define. typedef, and so forili) to that provided by 
the C++ preprcKessor, but with far more control. Consmnr data 
nienil:)ers are used in platx of the #define directive, and class 
definitions are used in lieu of typedef. Tlie end result is that Java 
source code ts much more consistent and easier to read than C++ 
source code. Additionally, as you learned earlier, Java programs 
don't use header files; ilic Java c timpiler builds class declarations 


Paul Ammann works as a Network Seaxity Engineer for a large logistics company. He speaks UNIX as a stxtjnd language, and likes writing programs 
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directly from the sSource axJe file!;, wliich contaiB ix)th dass 
dedar.uions and nietliod implementations. 

Let’s lcx>k at an example; Listing 1 shows a header file 
fi)r a ball class. 


Listing 1; The ball class 

Ifdefine COLOR^RED 1 
dcftne COLOR YELLOW 2 
defiriG COLOR BLUE 3 
define MATERIAL RUBBER 1 
^define MATERIAL LEATHER 2 


public static final int C0L0R_BLUE “ 3; 
public static final itit MATERTAL_RUBBER = 1 : 
public static final int MATER1AL_LEATHER " 2; 

//ViirLihk'S 
float diameter; 
int color; 
int material; 


In this version of ball, the constants are readily available For 
<)fher c:lasses to use. However, those dasse^s miisi explieiLly refer 
lo the constants using the ball class name: 


class ball I 
float diameter; 
int color; 
int material; 
h 


To move this code to java, the only change is to gel rid of 
the preprcKTessor #denne directives and the semicolon al the end 
of the cla,s.s declaration. You get rid of the #define directives by 
declaring java class memixTs that arc‘ static and final. For data 
members in java, the static keyword means there is only one 
copy for the entire class, and the final keyword meaas that they 
are constant, which is usually the motive for using #define in 
C/C++ code. Listing 2 shows the resulting Java version of tills 
class. Keep in mind that the java version Is not stored in a 
header file, liecause java doesn^t support header files; in java, 
definitions and dedurations are coml>ined in one place, the java 
source file. 

listing 28.2: The Java ball class. 

class ball f 
// Constants 

static final int COLOR_R£U “ I: 
static final int COLOOEULOW - 2: 
static final int COLOR_BLU£ - 3; 
static final int HATERIAL^RUBBER - 1; 
static final Int MATERIAL.LEATHER = 2: 

// ViriuljJcs 
float diaaeter; 
int color; 
int material: 

1 

Tlie Java version of ball pulls all the c:tinstants inside die 
class definition as static final integers. Witliin this class, you 
would then refer to them just as you would the previous C++ 
versions. However, outside this daas they are inaceessible, 
liecause they have b>een left at their default access type. To ouike 
them visible by oilier classes, you simply declare their access 
type as public, as shown in Listing 3. The staiemeni al>out 
default access isn't entirely true; you learn the whole sScoop 
about access types later in tills article. 


Listing 3: The Java ball class with public constants. 

cluuE ball I 
// CnnscuiLH 

public fitatic final int COLOR_RED = 1; 
public static final Int COLOR_YELLOW = 2; 


int color « ball,COLOR YELLOW; 


Strltctures and Unions 

There are three types of complex data tyjK^s in C/C++: 
classes, stmccures (stmets), and unions. Java supports only one 
of these data types, classes, java forces prognimmers to use 
classes wlien the functionality of struciures and unions is 
desired. Although this sounds like more work for the 
programmer, it actually ends up being more consistent, liecau.se 
classes can imitate structures and unions with ease. 
Furthermore, supporting sirucis and unioas would have put a 
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major hole in the whole concept of the Java language being 
olijeci-orienieti, Tlte Java designers really wanted to keep ihe 
language siinf^le, m it only made sense to eliminate asj>ecis of 
the language that overlapped. 

Converting stnicis and unions to Java classes is prciiy easy, 
'lake a look at Lbtiug 4, which contains a polar coordinate C struct. 

Listing 4: The C polar struct _ 

typedef struct polar I 
float angle; 
float magnitude 
\ POLAR; 

Notice dial tliis struct uses a typedef to establish the polar 
type. As you learned earlier, typedefs aren’t net essary in Java, 
lx:cause everything is an abject with a unique type. Java doesn't 
support the concept of a struct either. Listing 5 contains the Java 
version of the polar class. 

Listing 5: The Java polar class. 

clasg polar [ 
float angl0; 
float magnitude 

I 

In addition to changing the typedef struct declaration to 
class, notice dial the Java polar class Isn't followed liy a 
semicolon. This is a siiiall, bul often overlooked, difference 
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Ix^wccn Java and C++j semicolons aren’t necessary in Java 
class definitions. 

RiNcnoNS .AND Methods 

In C, code is organized intcj functions, which are global 
subroutines accessible to a prognim. C-F+ added classes and in 
doing .so provided class methods, which are functions that are 
connected to classes. C++ class methotls are very similar to Java 
class methods. However, liccause C++ sdll supports C, there is 
nodiing keeping C++ programmers from using functioas, 'Htis 
results in a mixture of funclion and method use that makes for 
confusing programs, 

Java has no functions. Being a i>ur€r ohjed-oriented 
language than C++, Java forces programmers tcj liundle all 
subroutines into class methods. There is no limitation 
imposed by forcing programmers to use methods instead of 
functions. As a matter of fact, implementing sulirouiines as 
methods encourages programmers to organize code better. 
Keep in mind that, strictly speaking, there is nothing wrong 
with the procedural approach of using functions; it just 
doesn't mix well wiili the object-oriented paradigm lhai 
defines the core of java. 

Because almost all C/C++ code contains some degree of 
function use, this is a particularly important issue when 
porting C/C++ code to Java. Fonunaiely, it's mostly an 
organizational change, 'I'he whole point of functions is to 
move ct)de into a logically separate procedure that can be 
called from the main program or other functions, You can 
easily recreate this scenario in java without having to 
^^objcciify'* the code completely. The solution is to move global 
C/C++ functions into method-only organizational Java classes. 
Check out Listing 6, which contain.s a series of string 
encryplion/decryption function prototyjK's. 

[isting 6. 'The C string encryplion/decry^ption function 
prototypes. _ 

char EncryptChar(char c. int key): 
char DecryptChar(char c» int key); 
char* EncryptString(const char* s. int keyh 
char* DecryptString(const char* s. int key); 

These functions arc global C functions that enaypt and 
decrypt characters and strings. Of ct>urse, in C/C++ there is 
no pure concept of a string; an array of characters is the best 
you get (more on that later in this article). A straight 
Funetion-to-method port of these functions in Java is shown 
in Listing 7. 

Listing 7: The Java string encryption/decryption methods 
encapsulated within tlie crypt class. 

class crypt ( 

public static char encryptChartchar c. int key) \ 
fi character tm-ryptitm cixle 

I 

public static char decryptChartchsr c* int key) I 
// character dtcg-piion code 



20 


Moving C and C++ Cork m Java 


MAC'l’liai • SlTTEMBER 2003 













^ V % \ 





iccXSiS NryoB'^MTOB 



V * ♦ V 




AccountEdge- i FirstEdqe 


MYOB AccountEdge 
Evolving with the Mac since 1989 

Small Business Management and Accounting 


www.myob.com/us 




800-322-MYOB(6962) 


Small Business. Smart Solutions: 


O MYOB 2003 






































publiiL static St ting encryptString (String int key ) i 

// string encryption ctxie 

I 

public static String decryptString(String s. int key) I 
// siring tlecrypiion csxic 

} 


(n Java, you have to package the functions as methods 
in a class, crypt. By dcciaring them as public static, you make 
them readily available to the entire Java system. The key 
aspect of the Java version of the functions is that their 
imptementaiJons are defined in a Java class because Java 
doesn't support the header/souice file organization. All class 
information goes directly into the class definition. Notice 
that ihe standard naming convention for Java meihod.s is to 
begin each melliod name witli a lowercase character. To use 
the Java methods, you have to reference them with the crypt 
class name: 

cbar c = crypt-encrypt Char (''a ’ . 7) : 

The only other change to the C fiinction.s is the usage of 
String objects rather than char jxrmtcrs because Java doesn't 
support pointers. You get into more details surrounding stiings 
and pointers a little later in tliis anicle. 

Procedural-to-OOP Conversion 

Although the Java crypt class provides working Java 
versions of the procedural C functions, performing this type 
of conversion isn't always enougli. The crypt cla.ss provides a 
good example of how you can maintain a procedural feel 
within a Java c?lass. Java is an ohjcct-nnented language, 
however, and you slujuld design your code to fit inltj the 
object-oriented paradigm whenever possilde. The crypt class 
is no excepiion to this rule. 

Examining the crypt class methods, it is apparent that .some 
Things could be modified to make the class fit into a more object- 
oriented design, listing 8 a)niinns the source code for the 
revised, objectified crypt class- 

listing 8, ITie revised Java >crypt class, 

class crypt f 

int key; 

crypt(Int k) I 
key =■ k; 

I 

void setKeydnt k) [ 
key “ k: 

1 

int aetKcyf) [ 
return key; 

] 

char encryptChartchar c) f 


// encryption code 

I 

char decryptChar(char c) I 
// dianictcr dreryption code 

I 

String encryptStrlngCStrlTig -^) { 

// string encryption code 

1 

String decryptStringtString a) [ 

// siring decryption code 

} 

1 

!n this version of crypt, the encryption key has l)een moved 
from a method pammeter to a data member of the class, key. A 
constructor was added that accepts an encryption key when the 
ol>ject is created, along with access mcthcxls for getting and 
setting the key. 'I'he public static declarations for the 
enciypt/decrypt methods have also been removed, which 
requires you io have an instance of the crypt ch.ss to use the 
methods, 'this makes sense, because the class now has a data 
member (key) that affects the methods. 

Tills revised design of tlie crypt class makes much more 
sense from a Java programming perspeciivc. Of course, it won't 
run any faster or perform better enciyption, but liiufs not the 
|K>ini. The poini is that oliject-orienied design practices are a 
fundamental part of tlie Java language and should followed 
whenever possible. 

Operai'or Overloading 

Operator overloading, which is considered a promincni 
feature in C++, is not supported in Java. Although roughly the 
same functionality can l>e impLemented as methods in Java 
classes, the syntactic convenience of operator fwerloading i.s still 
mis.sing. However, in defense of Java, operator overloading can 
sometimes get very tricky. 'I'he Java developers decided not to 
sup[X)n Qi>enitor overloading to keep tlie Java language as 
simple as possible. 

Although operator overloading is a pretty useful feature 
in C++, it.s usage is higlily dependent on the types of C++ 
classes with which you're dealing. For example» more 
fundamental C++ data structure classes, such as string 
classes, make fieavy use of operator overloading, whereas 
others may not use it alt. The amount of porting work you 
have in front of you depends on how much your C++ code 
relies on operator overloading. 

The only way to convert overloaded C++ operators to 
Java i.s to create equivalent Java methods w'ith the same 
functionality. Keep in mind that the Java methods will be 
called differenily iljan the C++ overloaded operators. This 
means you have to dissect your code carefully to find out 
where each operator is used and then convert the code to a 
method call. 

Let's look at an example; listing 9 contains a complex 
number class with overloaded operators. 
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Listing 9: The C++ Complex class with 
overloaded operators. 

class CoaipXeK f 
float real; 
float imaginary: 

Complex(float r> float i): 

Ccunplex ope£:aLQr+{const CoEnplcxSi c) const j 

return Compiex(Eeal + c.realt imaginary + c.Imaginary); 

\ 

Complex operator-[const Compiex& c) const I 

return Complex(real - c.real, imaginary ■ c.imaginary): 
I 


Ilie C++ Compfex number class supports overloaded 
operators tor addition and sublracfion. The following is an 
example of how this class is used; 

Complex cl(3.0, 4.0): 

Complex c2(5.0, 2,5): 

Complex c3 = c2 ~ cl: 

The subtraction of the Complex objects is syntactically the 
same as subtracting two fundamental data types. However, 
this capability adds a significant amount of complexity to C++ 
that the Java architects wanted to avoid. So, although you can't 
pnjvide the same syntactic approach in Java, you can provide 
methods with similar functionality Listing 10 contains the Java 
version of the Complex class, complete with method versions of 
the overloaded operators. 


Listing 10; The Java Complex class. 

claREi Complex t 
float re.^l; 
float imaginary; 

Complexfrloal r, float 0 [ 
real = r: 
imaginary = i: 

[ 

Complex add(Complex c) I 

return (new Coinplex(real + c.real. imaginary + c. imaginary)) : 


Complex subtract (Complex c) I 

return (new Complex(real - c.real, imaginary c.imaginary)}; 
] 


'Ihe most obvious change in the Java version of Complex is 
the renaming of Llic operator overloaded inetliods to add and 
subtract. The Java Complex class is used like this; 

Complex cl ^ new Complex(3.0. 4.0): 

Complex c2 “ new Complex(5.0. 2-5); 

Complex c3 c2 , subtract (cl); 


You can see how tlie subtraction operation isn't quite as 
intuitive using the Java approach. Nevertheless, it does work, 
Notice also that the Complex objecLs are creaied using the new 
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openiion This is a result of the differences between memory 
management in Java and C++, which you le:irn abiiut when you 
get into pointers a little later in this article. 

AirroMATic Cxieroons 

Automatk coercion refers to the implicit casting <jf data 
types that sometimes occurs in C and C++. For example, in 
C++ you are allowed to assign a float value to an int variable, 
which can result in a loss of mfomiation, java does not 
support C++ style automatic coercions. In Java, if a coercion 
will result in a loss af data, you must alw^ays expik'itiy cast the 
data element to the new type. 

'Ihe following is an example of an automatic coercion in C++: 

float f “ 1.1412; 

Int 1 ” f; 

Some C++ crompilers may actually generate a warning for 
this ccxle, but iCs not considered an erron In Java, on die other 
hand, this code results in a compile error. It is easily fixed with 
an explicii cast, such as this: 

flGflt f = 3.1U2; 
int 1 (lnt)f: 

Command-Lin£ Argumen js 

'I'he command-line arguments passed from the system into 
a Java program differ in a couple of ways from the command- 
line arguments passed into a C++ program. First, the number of 
parameters passed differs between the two languages. In C and 
C++, the system passes two arguments to a program: arge and 
argv. arge sfx.‘dries the nimilx.T of arguments stored in argv, argv 
is 3 pointer to an array of charaaer |>ointers containing the 
actual arguments. In Java, the system passes a single value to a 
program: args. args is an army of String objects that contaiiis the 
command-line arguments. 

In C and C++, the command-line arguments passed into a 
program include the name used to invoke the program. Ihis 
name always appears as the first aigument and it is rarely u^icd. 
In Java, you already know the name of the program t:>ecause it 
is the .same name as the class, so there Ls no Jieed to pass this 
infonnation as a command-line argument. Therefore, the java 
runtime system passes only the arguments following the name 
that invoked the program. 

listing 11 contains a simple C++ program ihai prints oui 
the argument list. 

Listing 11. A C++ program to print the ailment list. 

#include <tost ream.h> 

#include <BLrlug.h> 

void aainCioi arge. char* argvn) 

I 

fortint i “ J: i < arge; 1++) 
etjut « argv[l) << 

I 


Thi.s program .simply iterates tlirough each argumeni using 
a for loop, printing each to the standard output stream. Notice 
that the loop starts at 1 to avoid printing the name of die 
pn)gram iisclf (the first argumeni). Listing 12 contains the Java 
equivalent, die ArgPrint applic'ation class. 

Listing 12. The Java ArgPrinl class. __ 

public clasa ArgPrint I 

public static void main(String [] args) f 

for (int i = 0: i C atga.length: 11++) 

SyateiD. out, print in (args [i|); 

I 

The ArgPrint class contains one method, the main methcKl. 
Tills is the Java equivalent of the C/C++ main funaion; it is 
called w!ien the Java program i.s executed. Notice that the main 
method takes an army of String ubjc^cl.s as parameters. The 
usage of this array highlights another interesting difference 
lieiween Java and C++, arrays. All Java arrays have a data 
memlier called length that cun lie used to determine how many 
elements an array contains. In this case, length is used to iterate 
through the army t>f Siring arguments. 

I/O Streams 

You prohalily noticed ihe absence of the cout standard 
output stream object in the Java ArgPrint class. There's a good 
reason for this: java doesn't iinplement any of the standard 
C++ stream objects. However, It does contain similar 
equivalents. The Java System class implements three stream 
objects that are very similar to the C++ .standard stream 
objects: in, out, and err. You access these stream objects with 
the System class. 

The ArgPrint class showed how to use the out stream 
object to output text. T he out object is of type QutputSiream, 
and it contains a number of methods, such as printin, for 
outputting data to llie slaiidurd output sireain. Similarly, the 
In and err objects contain a variety of methods for performing 
stream input and output. In most cases, you can convert 
standard C++ stream I/O code to Java stream I/O code by 
simply changing the references from cin to System.m, and so 
forth. Becau.se Java doesn’t support operator overloading, 
you also need to change any « or » operations to the 
equivalent Java method calls. 

SXRINtiS 

C and C++ have no built-in siqiport lor text strings, 'fhe 
standard technique adopted among C and C++ prograininers is 
dial of asing null-ierminaied arrays of characters to represent 
strings. In Java, strings are implemented as first class objeas 
(String and StringSuffer), meaning lliat they are at die core of die 
Java language. Java's iinpiemeniation of strings as objects 
pnivides several advantages: 
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• The manner in which you cieale sirin^s anti acx'ess the elenieiiLs 
o( string Ls ctinsi.slent across ;ill strings on all systems. 

• Because the Java siring classes are defined as part of tlic Java 
language, and not part of some extraneous extension, Java 
strings function predictably evety^ time. 

• The Java siring classes pertbrm extensive ruiitime chet:king, 
which helps eliminate troublesome runtime errors. 

Allliougli it's easy to see the advantages of Java strings, 
converting C++ code to Java that makes heavy use of nulb 
terminated character arrays is another isstte. Next to pointers, 
string code is prt>bably the most troublesome code l() ctmveri to 
java. You simply must get dirty with the details and figure out 
exactly whar is happening to be able to change the code to use 
java string objects. The other problem is that cliaracter am^y.s are 
used extensively in almost every C/C++ program. 

listing 13 contains a simple C++ lb net ion that manipulates 
nulbtenninaied character strings, Reverse ft. 

Listing 13: ITie C++ Reversell function. 

ctiar* Reverselt (const char^ s?.TeKt) ! 
int ien = £ttlen(fistTc3it): 
char* dest = now charllenj: 

for (i ' (len - 1); i ><• Or i--) 
dost [len i ' IJ “ S7.Toxtfi1: 
return dest: 

I 

The Reverselt funclion takes an aitay of characters and 
returns an array of chamaers that is the reverse of ilie original. 
It simply tTCates a new array and copies e;Kli cliaracter from the 
original array in reverse order. Notice, however, tliat there Is 
nothing slopping you from writing code that overruns an array 
Ixnind, or even from manipulating the cliaracter pt>inters. Even 
tluHigh this code works fine, the very naiure of C++ makes it 
prone to potentially dangerous pitfalls imi>lciuenied at the 
programmer's discretion. Take a look at tlie Java version of the 
same function, reversed, wliicli is now a meihtxi in the Reverse 
cla.ss in Listing 14. 

Listing 14: llie Java Reverse class. 

class Reverse I 

String reverselt(String s) I 
int i. len = a. length(J; 

StringBuffer deal = new StringBuffer(len): 

for (i ^ (len ^ 1): 1 >" 0: 1”) 
dost .append(s.charAtli}) ; 
cetiinj dest.toStrlng(J: 

I 

1 

'i1ie Java reversell meiliod has no mention or use of 
arrays. In java, strings arc first cla.ss citizens implemented 
by the String and StringBuffer classes; thc 7 are genuine 
data types that can be manipulated like integers or 
floating-point numbers. All mudifications to Java strings 
must take place through the class methtjds defined Ln the 


String and StringBuffer classes, as you can see in the 
reverse It meihod. 

Fointehs 

Most developers agree tliat the misuse of ixiinters causes 
the majority of bugs in cyc++ programming. Rut simply, when 
you have pointers, you have tlie ability lo trash memory, C++ 
programmers regularly use complex pointer arithmeiic to create 
and mainiain dynamic data structures. In return, C++ 
programmers spend a lot of lime hunting down complex bugs 
caused l>y their cc^mplex pointer arithmetic. 

The Java language does not support pointers, Java provides 
similar functionality by making lieavy u.se of references. Java 
passes all arr;iys and objecLs by reference. This approach 
prevents common errors due to pointer mismanagement. It also 
makes programming c^asier in a lot of ways, because the correa 
usage of pointers is easily misundcrsi<K>d [)y all but the most 
seasoned pn >grani m e rs. 

You may be thinking that the lack of pointers in Java will 
keep ytm from being able to implement many data stnictures, 
such as dynamically growable arrays* The reality is that any 
pointer task can be carried out just as easily and more relialily 
with objects and references. You then benefit from the security 
(provided by the Java runtime system; it tx:rform,s !x)iindary 
checking on all array indexing operations. 

Pointers are no doubt the most difficult aspect of moving 
C/C++ t:ode to Java, because most C/C++ programs are riddled 
with t^ointer u.se* The first iiiie of attack in convening pointer 
c(xle is lo convert all charat:ier amiys to Java strings. Once you 
do this, youll probably Ix" suri^riscd at how much pointer^ 
tiefiendent cixJe was weecled out. 

The next phase of pointer conversion is object 
cTeation/destruction, In C++, die typical way objects are used is 
to create a pointer to an object variable anil dien use the new 
operator to create a new object and assign it to die variable* 
Once you finish with the object, you call delete on the pointer 
variable to clean up things. Thi.s procedure isn't all that different 
in Java; ips jusi missing the final step. 

In Java, objects no longer being used are automatically 
cleaned up by the java garbage collection system, which is 
typically implemenred a.s a low-priority system diread. 
Because the Java system itself handles cleaning up unused 
objects, yon don't have to worry about cleaning up after 
yourself. This may be your one opportunity u> make a mess 
and not have to clean up after yourself, so take advantage of 
it! To better understand the differencx+s between working 
willi objects and pointers in C++ and Java, let's look at an 
example. Listing 15 contains a C++ class with a memlier 
object pointer. 

Listing 15: The C++ Rocket class. __ 

class Rocket I 

Booster* booster «= 0; 

Rocket(3 I 
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booster " new Boost erO : 

I 

'-Rocket 0 I 

if (booster I*' 0) I 
deloto booster* 
booster 0: 

I 

) 

\l 

The coastaictor for Rocket i^!t!ali^es tlic booster member 
variable by creating a new oi>jea. Then the destructor for 
Rocket cleans up the booster member by deleting it and 
setting it to 0. This is a painfully simple example, but it helps 
to learn things in small doses. Listing 16 contains the Java 
version of this same class. 

Listing 16; The Java Rcxrket class. 

Rocket I 

Booster booster: 

Rocket() I 

booster nev BoosterO : 

J 

1 

The Java code is rnucli more simpler, even in this case 
where there is relatively little happening with the C++ 
pointers. Notice that the booster member variable isn't 


initialized to 0 in the Java version of Rocket, 'fhis highlights a 
subtle feature in Java; all member variables are set U> 0 or null 
if they are created without being initialized. Notice also the 
absence of a destructor in Lite Java code; the Java garbage 
collector takes care of cleaning up the booster object wlren it 
is no longer in use. 

Note; Java actually supports a method very similar ro a 
C++ destnictor, the finalize method. I'he finalize met bird is 
called whenever an object is destroyed by ilie gad^age 
collector. Ilow^ever, due to the nature of ilie garbage collector 
itself, Java does not guaramee that the finalize metlKxi will get 
called for all ol>iects. In other words, don't rely on it getting 
called in your code! 

If you're concerned about how Java gets by without 
using pointers, keep in mind that the Java system is certainly 
using pointers under the hood. The trick is that you are 
forced to do everything under the guise of references. This 
may seem like a pretty big limitation at first, hut once you get 
in the habit of using references you'll sec that you aren't 
really missing anything. Kniwing this, another phase of 
porting C++ code to Java is converting pointers to references 
in the C++ code before you even start ftmling with Java. Try 
converting some C++ code to being entirely reference-based 
and then take a stab at moving it to Java. You'll be in for a 
mucli smaller headache if you take this roiiie. 
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M11.TIPIJI INHERTIANCH 

Multiple inheritance is a feature of C++ that enal^les you to 
derive a class from multiple parent classes. Althtuigh multiple 
inheritance is indeed powerful, it is complicated Uj use correctly 
and causes lots of problems otherwise. It is also very 
complicated to implement from llie compiler ptirspective. 

Java takes the high road and provides no direel support for 
multiple inlieriianee* You cun implement functionality similar to 
multiple inheritance by using interfaces in Java, Java interfaces 
provide object method descriptions, l)ul contain no 
implementations. IcM's take a look at an example of C++ code 
that uses multiple inheritunce: 

class? InputDevlce : public Clickable, public Draggable I 
// dass denfilUon 
I: 

The C++ InputDevice class is derived lx>tli from the Clickable 
and Draggable classes. This means that InputDevice inherits all the 
data ineml:>ers and methods imfjlemenied in both of these 
classes. Tlie ckxsest you can get to this in Java is to make 
Clickable and Draggable interlaces, which can contain metliod 
definitions but no actual meiluxl c<xle or data members. The 
InputDevice class can implemeni iltesc interfaces using the 
implements keyword: 

class InputDevice implements CHckable, Draggable I 
// duiis defmftitjn 
I 

As you can see, you may have your wt^rk c‘ut out for you 
if you are tr>^Lng to move C++ code to Java tliat relies on lots 
of multiply inherited classes. Even so, the Java interface 
approach is not all tliut bad; you just have to juggle the actual 
method bodies and possibly implement more derived classes 
to contain them. Nevertheless, the primary goal of uniting 
separate logical organizaiion.s into a more derived one will 
still be attained, 

l!VHERrrANr:F Syntax 

ITie multiple inheritance example brings up another 
important difference Ixriween C++ and Java: inheritanc'e syntax. 
In C++, you specify inlieriiance by using a colon after the newly 
derived class, followed liy the parent class or classes: 

clii&fl B : public A I 
// class dcfiuilion 
I: 

In Java, the extends and implements keywords are used to 
indicate inheritance; 

class B sKternds A t 
// chiss defmUk>n 
I 

Fortunately, this change can be made in your C++ code 
as a simple search and replace, for the most part. The only 


hangup will be changing the syntax for classes using 
multiple inheritance, in which case you have to do some 
real work anyway 

Access Modifiers 

Access modifiers are supported in both C++ and Java, 
hut the methods of declaring tliem are different in each. In 
C++, you declare access modifiers as a label above a group 
of class members: 

clafis A I 
public: 

int X, y: 
private: 

float v: 

I: 

III Java, you can do the same thing, but you apply the 
access nKxlifiers a little differently. You set them for each 
individual declaration: 

class A [ 

public int x. y: 
private float v: 

I 

In this way, Java access modifiers aren't btxfis at all; they 
really are modifiers. Converting access modifiers in C++ code is 
pretty simple; just go through and remove each label, adding the 
appropriate modifier to each variable declaration or method 
following the original lal>el. 

Friends and Packages 

Java has no friends! 'fo prove it to you, Java dt)e.sn'l have 
any concept of a friend class, whereas C++ dt>es. A friend 
class in C++ is one that has acces.s to all the data and methods 
in another class, regardless of the visibility of ilie member 
data, Java has no exact ec)iiivalent to the friend concept, but it 
does have an access type that enables a specific group of 
c la.sses access to member data, which is somewhat similar to 
the friend idea. 

iJlis Java access type Is often referred to as the defatitt type, 
Ixfcause there is no keyword used to apj)iy it. You may al.so see 
it referred to as the friendly access m<xlifier, It has die effect of 
giving classes in the same pac:kage as the class in question 
access to the memixjr variable or method deelared with default 
access. To give a member variable or method default acces.s, you 
simply don't use an access modifier, like this: 

class A t 

public lut k; 
private Int h: 
int 1, ]: 

1 

In this example code, k and h take on the specific access 
modifiers they are declared with, and I and j assume default, 
or package, access. To convert friendly C++ code to Java, 
you should be able to combine friend classes together in the 
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same package and declare many of their shared mem hers 
with default access, 

Bcx)leans 

In tliere is no real boolean type; boolean values 
(ti-ue and false) are usually implemenred as integers, with zero 
lieing interpreted as false and nonzero being interpreted as 
nue. This usage resulted in somewhat of a half-iicarted 
attempt by C/C++ programmers to use hooleans in their code. 
Take a look at this examples 

if ( numliiveR] 
isDead = 1; 

7'here are a couple t>f assumptions l>cing rmide here liiai 
don’t sit well from a purist programming perspective. First, if 
statements should always be based on a boolean value. 
However, as this example shows, programmers often ex[>Ioit die 
fact that C/C++ if statements (and otlier conditional statements) 
oi>erate on values either being zero or nonzero, rather than tme 
or false, 'fhe isDead variable, which dearly has a IxKilcan 
meaning, uses 1 to re[>resent true. 

Unlike C/C++, Java supports boolean values as a type all 
their own. As a maner of fact, this example wouldn’t work in 
Java tiecausc Java if statements fully expect toolean types, not 
integers parading as hooleans. The Java version would look 
like tliis: 

IF (- -numlUves <= 0} 
isDead = true: 


The If statement has been changed to result in a boolean 
outcome. This outcome was implied in the C++ code, hui it is 
made cleart^r and more consistent in the java version, Tlie 
isDead variable has been changed to a boolean type. Notice that 
true and false are legitimate Java keywords (as is nuil) 

Most C/C++ code contains this “integer as IxKdeun” 
approach and will therefore have to lae fixed in a Java port, 
1 [Qwever, tliese changes are pretty simple and shouldn’t take too 
much rime. 

Summary 

In this article, you learned about the different challenge.s 
you are faced witli when [)orting C and C++ code to Java. 
Even though Java is a close cousin to C++, you saw how 
there are enough differences to make any conversion proce,ss 
a decent amount of work. On the other hand, the final 
benefits of moving your exi.sting code l>ase to java can far 
outweigh the potential difficulties you encounter while 
moving it. 

Tlie goal of this aritcle isn't to bog you down witli hundreds 
of detailed examples of complex code conversions, but rather to 
highlight the primary problem areas where llie liulk of the ctxle 
conversion will take j^face. If you lake it a step at a lime, you'll 
find tliaf moving C/C++ code to Java isn't all that hard. (If ir 
makes you feel any IxiUer, f wa.s able to convert a complex .set 
of sprite classes from C++ to Java in a couple of days,) Just l>e 
patient and think about how cool your code will be iimning live 
on the Web! 
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By Michael R. Hawey, Remeivs Columnist 


Mac OS X training from TackyShirt 


Training that doesn't suck, really. 


I'heir tag line is, "because training and fun are not 
mumally exclusive/’ For most training materials out tliere» 
liowevcT, that is not the case. Tlicn cairie Sam Cmlsinger, 
President and "Media Kingpin" of TackyShin Inc., a company 
he formed to produce quality technical education that Is also 
entertaining. Says Crutsinger, “This is the 21sl century. We 
should l>e able to present education in a way that keeps pettple 
engaged and get.s the point acr<)s.s. 1 liate to read. IDavidJ 
Poguc.s hooks are great, hut 1 still have to .sit down and read 
the thing to absorb it.” Add to that his inany years of 
experience in video editing and production, :incl a de.sire to do 
it differenl, and better than anyone else, and you have the 
ingredients for an interesting reci]>e. 

The core idea behind the training was to make it 
educational and fun. In other words, don’t bore the viewer into 
a coma. So, u> .sian, they chose to keep each of the segments 
under fifteen minutes (based on educational researcii published 
in a study from NYLT. Next find some talent. CiuLsinger called 
on some of the most well known, as well as some of the iiios! 
knowledgeable, folks in the Mac community. Andy Ihnatko, lojig 
time colymnist for Macworkl magazine, Bo LeVirus, auiht>r of 
many Mac related f)ook.s, Shawn King, lu)si and Bxecutive 
Producer of Your Mac Lite (an internet leased radio slicm), and 
Jolm Welch, a regular presenter at MaeWorld Expos, and 
columnist for MacTech magazine. He gcji tliese foitr names 
together, j)ul them in front t)f sets not seen belbrc in any 
technical training, and for twxi wrecks committed to tape pretty 
mtich everything they uttered alxnit the Mac, and Mac OS X, 
And, it seeiiis, stmie ihings not cjtiile Mae related (there are a few 
Easter Eggs on the D\T), one of which i.s outtakes of some 
bellintl the scenes shenanigans). Then came the hard pan, 
editing that mess down lo usalrle, and useful, nuggets, A 
daunting task wheti you take into account how niucli detail went 
into every .segment. 

The first fruit of this labor is entitled Mac OS X Disc h 
The Basics. Yeah, pretty dull title. Fortunately, the dullness 
ends there. On the disc is nearly four hours of fun education. 
In rotating pairs, Shawm, John, Andy, and Rob rake turns 
presenting some aspect of Mac OS X to the new user. Tiiey 
are accompanied by picture in picture computer screen 



shots, animations, and active desktop screens that sIukv 
exactly the what, W'here, and how of the topic they are 
discussing. And it is a discussion. They are not lecturing to an 
invisible audience, but rather seem to be carrying on a 
conversation with each other, and the view^er. Of course, 
the re arc other characters that constantly attempt to steal the 
spot light including chatting set pieces, and icons run amok, 
to name a few. Lhey do not, however, distract from the 
learning. They actually seem to enhance it, 

This is a basics learning tool, though. What can advanced 
users get out of it? Well, we watched it. We tlioughi it would 
bore us to death. This i.Sj after all, the basics. We. and you, are 
almost certainly well beyond that. Surprisingly, there are a few 
tidbits of knowledge to be had. There is always tlnit tme litile 
thing you never noticed before that w'ill help make you more 
productive, and this training may ju.si show it to you. Putting 
that aside for the moment, this product is aimed at those w^lio 
are starting from square one. So, w^e showed it to a couple of 
new Mac OS X users. One wlio was completely new to Macs, 
and a switcher from OS 9. Our newbie enjoyed it immensely^ 
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anti got a lot out of the DVD. He felt though, that some 
knowledge was presumed in the material, and said if he hud 
some experience with OS 9^ he %vould have gtiuen more from 
the training. Our OS 9 upgrade liked it quite a bit. too. Her 
main complaint was that Andy Ihnatko talked too fast, and 
lost her at some points. 

Our next question was how cun this material Ixi" useful to 
MacTech readers? By in laige, we figure ilie folks reading this 
review would nox get their investment out of it. However, every 
{)ne of us kiKJws at least one person that really, reaily, needs this 
DVD. Mayfie tliiit friend, colleague, family niemlxn will stop 
culling every other day if they watch it. for some of us, this 
training could helf) at the job. Coasultants, and adminisiraiors 
with dients and users in need of updatetl training will all find 
Tackysliiris material invaluable. 

All is not lost for the advanced user, however. Tliis is Disc 
1 of what wall ultimately be a four disc' set. No date ha^ been 
set for subsequent releases, but follow on discs will cover 
topics such as LroublcshcH>ting, and backup strategies (Disc 2), 
intermediate level training, and popular applications (Disc 5)^ 
Disc i is where most advanced users will gel tlie real goods. 
This disc is scheduled to cover under-the-hood kinds of 
topics, teaching the UnLx underpinnings, and advanced 
capabilities of Mac OS X. 

TackySliiri PresenLs Mac OS X Disc 1: The Ba.sics is 
currently availahle only from the company at their web site. 
Disc i is $39.99. plus $4.9S shi]>ping per item (international 
shipping is $9.90 per item), future instalimeiils are slated to lx 
the same price. You can even get yourself one of their t-shirts 
.sptJrting the cool 4‘ackyShirt k>go for $10.83 (one buc k more for 
us XXI. types). 

One final warning. When you do sit down to watch this, 
don't have any other plans. You may think yoifre just going to 
watch one segment rtral ttuick. but you arc just lying to 


yourself. I1iis stuff is digital crack, and before you realUe it, 
you1l have lost two hours to it Don’t have a wedtUng or a 
fiineml to go to, Ixoiise you will be late, and end up cheesing 
off [he others, e.specially if you are the guest of honor at either 
of those events. 
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REVIEWS 


By Ron Davis 

Book Review: Chris Crawford On 
Game Design 


T first picked up Cbm Crawford On CamG Design at the 
local bookstore because 1 am a wannalx? game programmer and 
often Icx^k at game design lxx>ks, 1 kept picking it up because 
there are a Ich of Mac screen shots and descriptions of Mac 
games in it. This is very imiisual for a game book, Ixit Chris 
Crawford is a game pn>grammer from way l>ack- 

One thing to know about tills lxK>k is it is very much atout 
Chris Crawford. Very oriented toward liis opinion and his 
plillosophy, with nary a line of code in die whole book. The 
book is broken up into two sections; the first part is an overview 
of game design and the second is a history of ail of the games 
Chris has wrinen. Because of tiiis his perscjnality comes rhrijugh 
very strongly. Maybe it is just hard to write about the c(x)l tilings 
in the code you've written and not t:ome olT seeming an 
egonmniac, but after reading the second lialf of the book I didn't 
really like Chris. Now that Tve read die first half, Td say he 
knows his stuff, but 1 probably woiildn'i want to hang with him, 
as he might feel the need to point out my Haws. 

Before you get a bad opinion of me, let me quote die 
Iseginning of the chapter entitled Random Soi 4 r Ohscrvatiotis\ 

“You would never guess it from my comments in ihis 
book, but 1 have a reputotion for, shall we say, 
outspokenness. Thar reputatkin is mostly on the mark, 
although it i.s often colored by the anger of tho.se 
whom I have skewered. My particular talent is not for 
detecting problems - anybody can bitch - but rather 
for phrasing my criticisms in a style that hits hard. 1 
hold euphemism and tactful ellipticity in contempt; 
integrity demands the expression of truth in the 
dearest and most compelling terms." 

'Ilie tone of liie liook is biting. He freely lambasLs everyone 
in computer games with a broad bmsh. So if you have a diifi 
skin and don't want to hear someone say all programmers are 
autistic, lack all srKial .skills, and will dierefore never be able to 
create a game diat reaches anyone but horny, violent young 
men, dan*t buy the book. 

Now on to the good stuff* The first half of the book Chris 
talks about the hi.siory of games, both computer and otherwise, 


the core concepts of Play, the recjuiremenLs of Challenge, 
Conflict and Interactivity in computer games. Then he goes on to 
discuss the missing dement of creativity in modern compuiCT 
games, and common mistakes game programmers, companies, 
and designers keep making. There is a cfiapter dedicated to what 
he thinks a game designer needs to know entitled neEdumtUm 
of a Game D(^igfier and one that lists a bunch of games he'd like 
to write. Then he talks about Slorytdling and how it is lacking in 
modern games anti people don't even seem to know it* Hie last 
chapter in tliis section of the book is the previt3u.sly mentioned 
tiia[iter of sour observations on the gaming industry as a whole. 

There is some great stuff in these chapters, and rather than 
go iliroiigh them one at a time, Tin just going to talk a little alxiut 
some of die stuff I thought was cof)l. 

In the chapter on challenge there is a long and 
interesting discTission of how the brain does things and how 
it learns. This he closely ties to game play and how the 
complexity of a game can increase without losing the player. 
Whenever our brains learn liow to do a complex task we first 
have to think of each little step, and this thinking is slow. As 
we repeat the steps we shove the doing of the steps down 
in to our cerebellum and no longer have to think about 
things to do them. When playing a game we do this as we 
learn the game. So stuff that was skiw and complex at the 
l>eginning isn't even thought about at the end. On the other 
hand, in games that are sequels, you either have to make die 
experienced player redo the now easy stuff or lose the new 
player with the overwhelming complexity of the game* 

Hie chapter on Interactivity is the core of his phtlosopliy of 
computer games, ti is interactivity that makes comfiuter games 
different from other games. Its really broader than that* 
Interactivity makes cximpuiers in general different. You can type 
things on a typewriter, but it is the interatiivity, the ability to 
react to mistakes and change them, that make a word processor 
more useful. Chris points out gtx>d computer games arc 
interaaive. Unfortunately many modern games have cx^a.sed to 
be interactive today. 

When Chris says creadviiy is missing from computer games 
today he’s talking alioul a couple of things. First nothing new is 
really happening. People are looking at the kind of game they 
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wynt Co write fiist anti them making up some half as^seci siory to 
do the same thing previous versions of this type of game did. 
Anti he Is right. Is there reaOy a difference between what the 
player did in Doom and wliat they do in Unreal? Yon nin aroLind 
and shoot things. They may lot^k preitien You imy have new 
weiipons, liul really you are still njiming aronntl shooting things. 

Also missing from creativity is an understanding of *‘art" in 
general in game design. In his chapter on the eduoiikjii of a game 
designer, he talks ulx>ut tlie lack of liix^ral arts eduattion in game 
designers. For the most p*irr game designers are pn>grarnmers, and 
programmers are a lot more tnierc‘sted in the challenges of creating 
the game technit ally, Llie algoritlims, the gra]:)hic engine, etc. than 
in the cfiallengcs die player fac'es. He gives a long Itsi of Ixxiks 
you should if you want to be a gatne designer Tlie list is sure 
to leave you feeling like you are completely unreiid. Ihere are only 
4 computer lKX)ks in the bunch, CQ€ie Complete, The Mythicni 
Man-Month, Algorithms and The Art of Comimier Programming, all 
of which are the Irask: texts every programmer slitjukl read. 'Itie 
other lists include everything from We Way 7bf?igs Work, to Ihe 
Story of Law, to Waldm by Henry Thorc^au, to Shakesjieare, the 
federalist fap(*rs. and the New Testament. 

1 did like hus suggestion in this chapter to ■‘take up a mildly 
dangerous hobby" like motorcycling or sky diving. Now I can 
tell my wife it is job related. 

The last half of the book is about mdivulual games lie 
wrote. It is an interesting history, written a lot like those 


conversations you always end up in w-hen hanging with other 
programmers who have been doing this a while. Talking 
about the challenges of a particular project, how they 
overcame them. You learn what he learned from each game 
and what he thinks did and didn't work. You also get a 
fascinating insight into the history of computer games. His 
first game was written on a cotnputer that had no display. All 
input and output was done through a typewriter. Yet he wrote 
a tank battle game for it. 

Chris worked for Atari and WR>te a nuinlx.T of games for 
them, 'flien when lie left Atari and had time on his hands, he 
bought a Lisa and startetl programming for tlie Mac. He wrote a 
numl^er of Mac games and talks afK)UL them in tlic l)tx)k. You 
can even go to his website (hnp://www.erasmata 2 z.com/) and 
download a number of them. 

SUMMARY 

Ovemll tliere is a lot to learn from this bcK>k. Not in the 
""How do 1 make 3n objects?” way, but in tlie liow sliould this 
specific kind of computer program, a game, work for the user. 
It is alx)ut iKdng a game designer, not a programmer. Aixjut 
creating all the stuff you do btdore you write a line t>f code, 
'HiaFs what makes it wortliy t)f your Ixxikshelf. If you want a 
programming book w^ait for my next column; irll he on a more 
technical ]->Qok. 
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COOL TOOLS 


By John C. Daub 

ARTIS Screen Tools 


Useful utilities for pixel measurements. 


A GREAT find! 

Between my duy as a sofiware engineer and 
cKcusionally fiddling with my hsoixom web site in ilie ev'enings, 
I Rnd myself so often being concerned with j>ixeLs. I want 
to know how many pixels long is this? How many pixels are 
there between this and that? Will that many pixels fit onto the 
screen? What color Ls that pixel? Are all these pixels lined up? In 
trying lo have my sr^ftware adhere to Apple's Human Interface 
Guideiines and to have my web site lie iisjthle by any web 
browser, I need to employ ttxils to help me count pixels lx!cau.se 
my eyesight is t<K> ptK)r Uj count manually. © 

Interface Builder lias the terrific: functionality of supporting 
guides and snapping-to when laying out your GUI, and the added 
cool factor having support tor adhering to the Aqua Interracc 
Guidelines, When designing in Interfac'e Builder, 1 always have 
this suppon on liecaitse it generally alleviates the need to count 
pixels for relative measuretnents, e,g. Ls the widget 20 pixels iVotn 
the left and right edges of the window^ 14 pixels of vertical 
spacing, etc While interface Eiuiidefs sLipj:K)rt is usefuf there are 
other measurements that sometimes need to Ix^ taken. For yearn I 
used a tcK)l called colorScope, whkh served my ‘"pixel” needs 
quite well. Ilowxwer, colorSco|X^ didn't make il over to Mac (').S X. 
T dug anmnd the 'net looking for a replacement uk>I. I foiintf ihc‘ 
ARTIS ScTcen TcxjIs, a colkxiton of four simple utility appliattions 
aimed towards solving a s|>ecific stiecn issue; measuring, 
ensuring fit, magnitlcarion. and easuring alignment. 

ARllS Screen Tools is an application suite consisting tjf: 
AK'flS Screen Ruler, tlie screen ruler for your desktop; AlfH.S 
Small StTeen, small streen sizes on your deskiojr; ARnS Screen 
Loujk% the magnifying glass for your desktop; and AR'HS ScTcen 
Guides, visual guide lines on your desktop. 



figure I. Conteim of ARVS Screen Tools 2. 5,^. 


The. Tooi5 

Screen llulefs puq>o.He is measuring. You are given IxRh 
horixtmtal and vertical rulers by which you can measure items on 
screen. The rulers float atK>ve all other windows, allowing control 
over their opacity, as well as ecsnirol over the unit.s and length of 
the mien Screen Ruler allows Ibr quick and easy measuring of 
screen items, and is as simple to use as a physical niler 

Small ScreeiTs puqKxse Ls to help you easure your window 
and its contents fit on seamen. As develojK'rs w tend to he spoiled 
wiili a k>i of screen re;il estate, but many of our useix are still using 
small f>40x480 .screens. Small Screen places the thin black outline 
of a rectangle on screen wired lo the sizes t>f well-established 
.screen sizes, e.g. 640x480, 1024x768, or you can establish your 
own sizes. When Small St:reen places the Ixiimdary on screen it 
can adjust for items such as the nienulxtr so you can truly .see how 
your window will fir and display on a mtmiKjr tjf that size. Small 
Screen also has a Brow.scr Qintent mode which ftirther adjusts the 
IxiuncLiry rectangle to consider l>rowser window content such as 
ltx)ll>ars and scrolllxirs so you can .see how the more popular 
brow.sers will sc|ueeze your content and force it to rellow. Handy 
for debugging your ctxle [)rior to |X)siing it to your wel> site. 

.Screen Loupe is a inagiiificntion tool, like Apple's Pixie but 
more jx>werful, Wtili Screen Loupe you can view pixL-ls ckxse up, 
up to 8x magnification. You t an also view information alK)ui the 
pixel under the cursor: glolial ccx>rdinales, RGB color, JISB color, 
and HTML code color. I rememl:)er using this sort of UKtl when 1 
was working on the Graysc ale implementations of the l^owerPlani 
Appearance Clas^ses. 1 liad lo determine I he correct patterns for an 
indeterminate progress bar and chasing arrows so 


John C Daub lives in Austin, Texas USA with his wife, three children, and all the BBQ he can eat. You am contact John at hsoii^hsoi.com. 
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LGAPro^*ressBarlmp and LGAChasingAnrowsImp could 
reprcxiuce them. IJeiiig able to z*30iii in on the pixel paiieras of 
the Appearance Maruiger-genenited widgcLs and pick up the RGB 
color values w^us a nec'essary pint of recreating those widgets, 
Si'reen Guides is a way to add guides when you can't liave 
guide supjxjrt or wish to augmeni existing guide support. 
Guides are line.s that help you fxjsition your layout hut don't 
appear in the final layout; they are tools to aki tn .supporting 
proper alignment of your content. You begin working in the 
Screen Guides application, creating and moving guides as 
necessary lor your layout pur]>oses, When you switch out of the 
Screen GiHides application, the guides are no longer editable and 
you can Ix^gin your work, 'fhe guides float a lx we your windows, 
so dieyll lie just where yotfll find liieni useful wliile you work 
on your kiyout, but they won’t get in your way. 
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/•'fgure 2 : AJiTlS Screen Tools al mjrk. 


The ARTIS Screen Tck>Is are olTered as sharew^are, U.S$9.95 
at the time of this writing, for the suite of all four Once 
you register, functionality is unloc^ked in die applications: in 
Screen Ruler, the ability to luse the vertical ruler; in Small Screen, 
the Browser Content sizes; and in Screen Guides the ability to 
use vertic:al guides. When 1 contacterl the author for support, the 
response was quick, courteous, and lielpfuL 

'Hie AR'flS Scrtxm Ttxds work together as a nice suite For 
handling pixcbineasuring needs, bach application is lightweight 
and focused in its purpose, and serve to addreSvS needs that bf.>th 
software and web developers am encounter m designing, testing, 
debugging, and development of a successful user interface. If you 
find yourself needing to mejtsure, fu, magnify, or align pixels, 
you'U find Alfl'lS Screen TcxjLs a useful addition to your uxilkit. 

References and URL's 

ARTIS Screen I'oob - http://www.artissoftware.com/screentools/ 

Apple Human Interface Guidelines - 

http://developer.applecomftechpuhs/nrtacDsx/E5sential5/AquaHIGuidelines/i 
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UMTAIUCLiniC 
THE WEB 


By Kevin Hemenway, Omnipotent Yodeler 

Enabling CGI Scripts 


Prepare your server for more powerful 
dynamic capabilities 

Last month, we started down the road i>f adding dynamic 
content to our web server with the use of Server Side Includes 
(SSI). Often regarded as “sinipie" compared to languages like 
Peri and PHP, they can provide some quick turnaround ct> minor 
features like small single-ifein databases, changing content based 
on user whim or URL. and so forth. Kegardless of whether you 
plan cm using SSls or not, we laid some important groundwork 
with our understanding of how modules work, Apache's ^block” 
configuration fomial, and a soft introduction to GET and POST. 
All relatively Lego. Let’s break out the Technix. 

A Quick ‘How do ya do?' To CGI 
SSLs are built into Apache througli the use of a module— 
when tlieyVe enabled, the web serv'cr liandles the request of a 
resource, prcxresses die SSI statements within, and dicn sends 
the final output Irack to the user. Since Apache is a web server 
and not a programming language, die eapabiliiies of the built-in 
SSIs are minimal—ihey’re not intended to lx? a full-fledged 
Cfxling environment, and they never will lie. 

This is where CXil comes in. Meaning "Common Gateway 
Interface”, il defines a way for a web server to inieraa with extermil 
programs: Apache handles the refjuest, sends some relevant 
informaiion to the requested resource, and mists the resource to 
handle die re.st (including sending tiack the final content). If the 
resource doesn’t respond pnopedy (eidier due to bad jmigraniming, 
incorrect permissions, etc.), Apache generates an eitor. 

What does this really mean? Ultimately, it allows you to use 
any shell programming language to "do stufT Iiefore showing 
the results to your visitors. Whether this meaas displaying 
content from a database, resetting passwords, saving a comment 
to a weblog, etc., as long as your program finishes properly, 
Apache doesn’t give a darn. 


Mast commonly, these “CGI scripts” are written in Perl, but 
you can use PHP, C, B;tsli, Ruby, Python, and anything else you 
may l:»e interested in. Likewise, you can use diem all in tandem^— 
ytm're not locked into any one programming language at any one 
time. Be forewarned, however: you are k)t:ked into security 
concerns: anyliiing possible in your programming language of 
chf)ice is doxtble within your CGI script, including deletion of files, 
exhitusiion of memory, buffer averilows, p<Mjr security, and 
impolite use of rcsouices. Add in the fad diat all of these errors 
in judgment liecome publicly mn-ahie by anyone who accesses 
yctur .server, and you've got a whole mes.s of potential trouble. 

Enabling The Gateway to Your Soufi s 

U'arning about CGI Follows my {>ft-repeated methotl of 
"seal'd 1 the httpd.conf for the feature you want". So, oj>en up 
/etc/httpd^httpd.conf in your favorite text editor and search for die 
word "CGr—our first two matches l<K)k vaguely familiar: 

LoadXodule cgi^iiodule llbejcec/btTpd/ciod_cgi»so 

AddHodiile jnqd_cgi,c 

if you recall from our previous articleSi Apache contains 
most of its fcalures broken up into modules—tlie equivalent of 
plugins. To enable a module, iwo lines must exist uncommented 
(m)t preceded by a # character) in the httpd.conf file, an 
AddModule and a LoadModule. As previously with SSI, so too with 
CGI: our two lines alrt‘ady exist, anrl are already enabled. Let’s 
move on to our next search result, which is also similar to what 
we saw last nionih: 

(Directory "/Library/Webserver/Documents"> 

*'l bui may alwi be "Ntine'V'Air, or any ctiinbinaUun of 
* ■‘IndcxesL'rndudes'V^^^l^owSymLinks’*. "IfxccGGr, 

^ or”MuUiVrCTV5". 

Options indexes FoliowSyiaLinks HultiViews 

AllovOverride Hone 

Order allow.deny 

Allow from all 
(/Direcroi:y> 


Kevin Ileinenway, coauthor of Mac OS X tlacks, is licUcT known as Morbus Iff, the tTeaior ol' disobey.com, which bills itself as "coracni for the 
disconlented." Publisher and developer of more home cooking than you could ever iiiugine (like tlic popular open-.sou reed aggregates AmphetaDesk. 
the best-kept gaming .secret Gamegrenexom, articles for Applels Internet Developer and the O'Reilly Network, etc.), he’s been spending the Iasi two 
month.s listening to every fK>ng in his iTune.s library twice. Coniact him at mofbus^disobey.awn. 


38 


EhiABLLNG CGI Scripts 


MacTech • 2003 













Whereas last article ihc above result was triggered by the 
word Includes, it"s ExecCGI diis time around. Unfortunately, 
explaining ExecCGI without some prior knowledge will 
cause a little bit of confuskm, so let's skip ahead to our next 
few matches before wc go much further IVe truncated them 
for relevance: 

# SertpLAUjUifnus coiiirols wliich directories 

# ctmuin i^erver scripts. ScripiAUascs arc csscnrially 
^ the same as Aliases, extepl that documems itt the 

# fcalfiame directory ire treated applicaitons aod 
^ run by the server when rct|iiested rather than as 

# dociinit'iiLS srni to the client. 

# 

ScriptAiiss /cgl-bi:ny ’’/LIbrary/WfibSnrver/CGI‘Executables/ " 

# "/Utwajy/Wd)Smtr/CG14sxc^ sbmik! be changpd 

* to whatever yijur StriptAliased CGI directory' exists, 

* if you have that cinifif^red 

# 

<Di r e 11 0 ry "7 Li b r ary / Web Server/ CGI - Execu tab 1 es " > 

AilowOvercide None? 

Options None 
Order allow,deny 
Allow from all 
C/Birectory) 

The most common CGI configuration is all about 
segregation: “^only files in this directory should be executed 


as programs—everything else, anywhere else, are just plain 
old files that should he processed norimlly.” From the 
standpoint of an overbearing system administrator, this 
makes sense. With only one directory that can execute code 
unconditionally, and only one person (you) who can pui 
programs there, it can bring a little sanity to your day-to-day 
security paranoia. 

Tills Is how^ Apache is configured by default, and the above 
httpdxonf snippet shows the.se settings. Our first directive, 
ScriptAlias, leis us pick and choose which directory weM like 
CGI scripts to Live in. AnyUitng within that directory, CGI script 
or not, will l>e executed by the web scTver as if it were a 
program. If something goes wrong, Apache will return an 
“Internal Server Error’’ to the requesting user-agent (ie. your 
visitor's browser), 

ScriptANas a>asists of two space-separated parts: the take 
name and ilie real name. The fake name, /cgi-bin/, defines what 
URL will be tused to access llie real name, 
/Ubrary/WebServer/CGI-ExecutabIss/. In the currently contigured 
settings, whenever we access a LIltL like http;//127.0.0.1/egi- 
bin/printenv . we’ll really be accessing ilic maicliing file stored at 
/Library/WebServer/CGI-Executables/printenv. 
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The M.'amd pan of our configuration is a block dirc^aive 
focusing on that specific IcKration of our hard drive. It merely 
ensures tliat said directoiy has no special privileges besides that 
ScriptAlias: ii can'i override anything in the Apaclie configuraiion 
(AllowOverride None), and lliere are no special capabilities 
(Options None) associated with it. 

At tills point, if you only care about the directory 
segregation of CGI, you can skip over to our next su!>heading, 
’‘Let's See One of These CGI ndiigies In At ii<>n!" If, on the other 
liand, you’d like to hear me get high-and-niigliiy over the ‘‘rigliC 
way of doing things, read on, 

CGI EVERYWHERE; liRiLLLwr PlSYaiouxiit al THRniJ^!” 

In die very first "Untangling the Web”, I [iirofessed a 
fondness and desire to teach you the "right” way to create URLs 
(MaiTecb Magazifw, June 2003, *Vntangling The Weh^, 
"Familiarity That Breeds An Uh-Ohf^. A g<xxl URL will reniain 
in existence until the du.sk of time, never needing to l>e changed, 
never needing to lie refactored. It's not a snap-dec ision: if you 
find yourself changing your UltLs around, you designed your 
site poorly (from an engineering, not visual, siancipoint). 

One of the maxims, which Til reiterate here, is that "Your 
URLs Should Not Reveal Your Technical Capaliiiiiies”. This 
has absolutely rioihing to do with the ofHrialigned "security 
through obscurity”—the belief that hiding information makes 
you less susceptible to risk. Instead, removing ihe 
technicalities of your UR I- will allow your site to grow w'ith 
your needs. 

Consider the default configuration of CGI: anytime you want 
to add some dynamic: functionality to your site (with Perl, Pytlion, 
etc,), youVe got to slick your .st:ripi in a directory and point to it 
with a URL like http://127,0.0,1 /cgi-bin/add userpi (w^here .pi 
denotes a Perl script) or http://127,0,0.1 /csi-bin/del liscr.pv (.nv 
denoting Python). What happens, though, when you no longer 
need CGI scripts, but liave moved to an enilx,‘tided language like 
Htidiienly, all of your pages that point to that ugly /cgR>in/ 
URL are f>roken, useless, anti inaccunite. You find youiself 
refacioring pages to point to new locations. 

Tlie soluliern? Remove /egi-bin/ and the file extension from 
the URL. By clearing iliis nctedle.s,s technical emit, you get 
stronger addresses with less need for change. 
hltp://l 27.0,0.1/admin/add user and 

http://127.0.0.1/admin/dcl user contain no indication of tlie 
technology liehincl diem, merely tlieir purpose in the granule 
scheme of tilings. 

WeVe already halfway tlirough removing /cgi-bin/ from our 
URLs (file exteasioas 1 keep potting off, but I’ll get to em 
eventually, T promise!). Our very first match for our "CGf” searc'h 
was for an ExecCGI addition to die Options line of our rexjt weh 
directory (/Lfbrary/WebServer/Documents/). ExecCGI works 
similarly to Includes, which helped get our SSLs running last 
mondu By adding it to the Options line of any Directory we, like 
SSls, are telling Apache to allow CGI scripts at that location: 

Options Indexes FollowSyiiLinks HultlViews ExecCGI 


To make the comparison even more apt, there’s one 
other thing we need to do before we can use CGIs wherever 
we need them: we need to add a handler that says “Apache! 
Listen u]ij Whenever we request a file willi this extension, we 
want you to treat it as an executable program!" This handler 
was al.so needed last month—we told Apache that anytime it 
ran across a file with an shtml cxleasion, it should process it 
for SSls statements. 

Tliankl'ully, i here’s not much brain work involved here, as 
our final relevant search maidi for “CGI" brings us to the below. 
Simply uncomment the Add Handler (by removing die #), restart 
Apadie (sudo apachecll restart in your Termitial) and you’re 
ready to go: 

# If you want to tme server side includes, or CGI outside 

# ScrlptAliased directories, imctnnment the following lines. 

# 

# To use GGl scripts: 

#Addllsndler cgl-script ,cgi 

I'wo caveats that may lie running ill rough head: "what 
a!x)Ut the cgi extension?” and "w'hat alx>ut that security brouhaha 
you cautioned us alK)ut?" Concerning the file extension, yes, 
w'e're swapping /cgi-bin/ fijr cgi, l>ui this will never lx^ an is.sue 
once we remove the need for them in our URLs. As for security, 
there's m>t much I can say lx:sitles "be careful”—you'll no longer 
finve the niceties of a single and central directoiy^ far your code 
execution, so double and triple check tlie .scripts you 11 he 
pn>grainming or using. I'll talk a little more about script .security 
in next month’s column. 

Let’s See One of These CGI Thengies In AtxfoN! 

Browse to your /Ubrary/WebServer/CGhExecutables/ 
directory, the default kKution that Apaclte has lieen configured 
for CGI script.s. You .should see two files, printenv and test-egi, 
there already. The,se are some default Apache CGI scripts that 
will help you quickly test if things are a-ok. Since CGI was 
already pre-con figured in the httpd.conf. we should lx: able to 
just load one of these files in the hrow^ser and see some 
fireworks, right? Load http:// [ 27.0.0.1 /egi-bin/test-egi . and w^e1! 
receive* die response in Tigure 1. 

Forbidden 

Ydu hiinf h* EicceTt fia ito Mn«r 

(/ J.27 Str^rr <j4 Jfjcn/ f*irrt lltJ 

. ' . . "' n -fte 

Figure l:An error after loading ourlesl-cgi, hut why^ 
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If CGI scripLs were already configured, why this rather rude 
error message? Let's check Apache's error_log, whicli will always 
contain some sort of light l>ull> enlightening respotise. After 
Rinning tail /var/log/httpd/error_log on the command line, we’ll see 
something similar to tlic Ix^low as the last line of output: 

rsun Aug 17 20031 Urroz] [client 127*0,0,11 file 

permissions deny server execution: /Llbrary/WeSServer/CGT 
Executables/test-cgi 


This LS one of the more common errors you’ll experience 
with CGI scripts: the test-cgi file doesn’t have the proper 
credentials to be considered an executable program. 1 won't get 
iritcj the vagaries of file ownership or permissions, but follow 
through llie Ixilded commands below to give IkkIi of the default 
CGI files '^execute" access for all iksers: 


> cd /Library/WebServer/CGI-Executables/ 

> Is 1 
totul 24 


rw‘r“-r-“ 

1 

root 

admin 

5398 

Jul 

27 

2002 

printenv 

rw-r’-r-- 

1 

root 

admin 

75/ 

Jui 

27 

2002 

teat-cgl 

> sudo chmod 

755 * 







Paesvord: ** 









> Ifl -1 









total 24 









rwxrxr-x 

1 

root 

adfflin 

5398 

Jtil 

27 

2002 

printenv 

rvxr-Kr-x 

1 

root 

admin 

757 

Jul 

27 

2002 

teat-egi 


Now, let's try our URL again. Figure 2 shows our new 
txi[pui: 



hiip.//l 27 ,O. 0 . 1 /cgi-bin/ie 5 t-cgt v - . 

A A I fo \ r+1 0hitp:/7i;O "^a- He>io! 



CGl/l.O test script reports 


U. argv is 


SERVEK^SorrWAHE » Ap*eho/1^1 * 27 (Darvin > P«P/4 a,2 
SERVER^WAHE * disobey.Ioo#i 
1 GATEWAy_INTERFACE • CGI/1.1 
I SERVEfl^EROTOCOL ■ KW/I ,1 
SERVEH_PORT ■BO 
REQUESTHETHOD - GET 
HTTP^ACCBRt - •/> 

PATH_IKrO - 
RATa_TRAiaSLATeD • 

■SCRIPT_H«1E - /egi-bin/test-cgi 
OaER¥_STalNG ■ 
i REMOTE_llOST ■ 

1 REHOTE_ADDft - 127.0.0.1 
j REMOTE_USER - 
i AirTtt_TYPE - 
COITTENT TXPE - 
COJITENT LEWCTH ■ 


figure 2: The correct output of our ieat-egi script. 


Figure 3 shows tlie output from the other script, 
://127*0.0.1 /egi-bin/printenv: 


CCt Rfoctss tnvlroiifntnt 


0 fmo: //12 7.0.0.1 * HeOol 


CGI PrtH.t'iss Envininmem 

Veriobk 


query string 


SERVER ADDR 

127.G.a,1 

HTTP ACCEPT LANGUAaE 


SERVER^PROTOCOL 

«TTR/1,1 

HrrP.CONNECTION! 

keep-alive 

SEaVER,SIO.NATURE 


REMOTE l'ORT 

S0G13 

HTTP ACCEPT 

*/• 

H1TILUSER_A0ENT 

Ho5ilX«/3i.O (Ma€iiiC.04bt U; RRC Ha 
liRc ! 

Gecfcal Seiari/as i 

GATEWAy INTERFACE 

cai/i.i 

HTTP.HOST 

i27*a.«.i 




figure 3: Similar ouiput from the defaitJi prinimtv script. 


If you followed the instaiction.s under the ’"CGI 
HVKRYWllERE!" subheading, you can also move eitlicr of the 
printenv or test-cgi scripts out of tlicir current location and stick 
them in /Library/WebServer/Documents/ witfi a cgi file extension. 
Once you do so, you should then be able to run diem under the 
tK)n-/cgi-bin/ LIRL and receive the siime output (if not, what’s 
your first course of action.^ Check the error Jog!). 

Assuming you get similar output as Figures 2 and 3, wliat 
does all this giblieiisli mean? Wliat exactly did we just do? Both 
.sc'ripLs show a numlier of efwirormmit variables, which is just a 
fancy tenn for data that exists ^^invisilily" and floats around 
waiting to be used or read. .Some of the variafiles were set by 
ihe browser (like HTTP_USER„AGENT), and .some have been set 
by the server (like SERVER^PROTOCOL). When I first 
introduced CGI, I mentioned that Apache "sends some relevant 
information to the requested resource". 'ITiis "relevant 
information" Ls stored in environment variables* 

Environment variafiles can exist outside of your web server 
t(K>. For instance, if'you run printenv in your Terminal, you'll see 
a listing of variables similar to Figure 4: 


hMMf 
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I grrtuti*! ^ Imh bah llTvPlJ — 9^*24 


> prtntvw 

PWD»AlieT9<^rbue 

CVS_COOTk-^ :txt uortuLs4cv9 .g^^wtodinfc«^ ifwb ;^Brn)t/ciipMtii4^ 
SCFLjCATAtOC^ J LES^/aw/etc/sgsl /nta Log 
»«h.CATUjOC^ ILEWiw^tc/» l^otsl og 

liww' I IMEicr IS 

tWVA l>Waf/ihn/Kn: Aar/itarft/te :Aiir/locol : AJcr/OCUfib/Mn 


CVSjeH4«i 

TCnCAPw### 

limPATH-/ (v/shorw/1 nr 0 :/iw/ifir o o 

3«LL»/t>i>VtCSh 

HDlC^/IJttdtK/BOrtniA 

lERH-vtUeO 

PA f iW>wi/bi n 3 /9w/3b ui :/b^n ;/^tn: AMT/Din :/u»r/ibtn!? Awr/toea( Vhinj/k^^ toed t y<ir nVPQi 
11 t«/e I rv' oool/sbin :i'l!9er9/H9liu«/^ L loot icfw e Ainx«/Pvbi».^ikriOMKti/n t Botoy *t^at 

t4i^Hrtt/codi/:/lJsdr t/MHrbJi/Car)qMe4t/&( 9ob€y .OMu^te9^g«n/t/co4iy tdeciwoo lAwAl UiiM»tn 
JU50LllXt_aitDtJlC.ftdf5 J«:S 
^V^/btiVlpriloCanv 


■>u 


figutv 4: Environmetii mhahies in your Temiinul. 


Believe it or not, weVe dealt with environinciii variables 
already in this series. In our aniclc on Server Side Includes, we 
checke<l the $QUERY_STRING variable ro see whkili quote 
should lx: displayed at the user's ref|uesL, If you check back to 
Figure 5. you’lJ see an environment variable named 
QUERY^STRING, whicti is cunendy empty* Fry adtiing ?q02 to 
the end of our URL ( http://J 27*0.0.1 /cgi-bin/printenv?qQ2 ). and 
.sec how tliat changes the oni put (Figure 5): 



figure 5: Our QlIHf^YJUTUNG now has a mine. 

With the above two scripts wi^rking correctly, our CGI 
capabilriies arc ready for use. 

HoMEU'OKK MiUJGNMENTS 

In <jur next column, well chat further alx)ui CGI: how to 
iK’gin creating our own, the mo,st eontinon errors during 
development and deploytnenl, security issues we should be 
aware of, and how to find the "good ones” from ilie immense 
ocean of crap. If we have time, well show you liow to install a 
few that have srkkI the Le,st of time. Tor now, students may 
contact the Le<tcher at mofbus@disobey.COm. 

* Take a look inside printenv and test-cgi in a text editor. 

■ View the printenv sc'ript from various browsers and machines. 
Dcicrtiune how the ouipuf changes, and .see if you can figure 
out what each setting actually means. 

• Forgive me for not including anything amusing in (his anide. 



Introducing EaryOraw - tlie fun, easy-to-use Mac OS X 
design tool that lets you drew like a pro! Now you 
don't need to be a graphic artist to create great 
illustrations. EaryOraw's vector-based graphics and 
editing capabilities make it easy to create technical 
diagrams, flow charts, and hu si ness commupicatians 
as well as commercial line art illustrations and graphic 
elements for application software and web design. 


Learn more about EazyDraw today! 6et big savings 
buying direct from our online store. Visit us at 

w ww. ea z y d ra nv.co ill 

(That's easy with a Z). 


Ct ^^003 Dtiwfrft Optics* LljC. Alt nflhts rpB«iv«d. 

EazyDrew anU U>e tjox tools' wo irwlBiTifiritiE erf Ookiyra Oi^rUc^ UjC. 
Mac ami Buill for OS K ara tradamults of Apple Compuler. Inc. 


Eazyd^Draw 

Make Drawing Fun on os X 
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SOFTWARE 

TESTING 


Hy Dai’e Kelly 


Automate your testing... with Eggplant 


Exploring a new tool for performing 
automatic tests 


Test Altohvtion on the Mac - A Brief Overview 

Your ccxie hns bugs in iL Wliat? So, you don't like hearing 
that, eh? Bui it’s not your fault. All software has bugs. Finding all 
the bugs in your software is a big job so you need all tlie lielp 
you ('an get, right? 

fiug finding is an art that complements code wriring. 
Somewhere along the way .strmeone (probably an overworked 
quality' engineer) figured out that time and effort could l^e saved 
by using automated testing. There are several automation tools 
available for testing Windows software including software from 
Rational Mercury Interactive, Segue Software, and i)ihers. But, 
unlil recently there was nothing that come close for Mac OS X. 
In Mac OS X, the tester has had to rely only on AppleScripi or 
Perl for rest automation. It iloesn't take ttx) long to realize diat 
although they are very powerful iools, neither AppleScript nor 
Perl are adectuate for testing some things. GUIs and functionality 
that am only lx accessed through rhe st>ftware Ixing tested to 
name a few. Even tlie new GUI Scripting (System Events) Ixta 
software (see http://www.applexom/applescript/GUIf) does not allows 
the GUI of some software to be tested. We're now going to take 
a look at Redstone Software's Eggplant software for testing Mac 
OS X software, 

Redstone Software, Inc. is a subsidiary of Gresham 
Computing pic, which is !3asetl in Soutiiampton, UK. Gresham 
Comf>uling (GHT) is traded on tlie London Sltjck Exchange. In 
late 2()01, Gresham Computing starred work on a new product 
internally named Operation Scrc^aming Eggplant. Their goal was 
to deliver a product with high ease-of-use for the neophyte yet 
still offer powerful capabilities for the experienced tester. The 
Mac OS X platform was chosen as the base OS for this prcxlucl 
for two major reasons. First, tliey wanted to establish the product 
Ixfore competing in the PC marketplace where cximpetiiion is 
much more fierce. Second, tliey Ixlieved that Mac OS X had the 
right features and extensibility to supp<jrt the enterprise market. 

Redstone Software, Inc. was created in c^arly 2002 and in 
October of 2002 became the first company to deliver a cros.s- 
platform automation tool to the Mac OS X platform, 'Ihey stuck 


with the code name and named thek product Eggplant. Their 
belief is that automation pRxlucIs of this kind are traditionally 
ttx> complex and require specialized develofiment skills ihiii are 
rarely found in testers. In addirion, they also iDelieve that very 
few automation projects have l>ecn successful, although there are 
aiscs where automation has w'orked. In tlie.se oi.ses automation 
is peifomied for tests requiring special or repetitive 
computations, such as acceptanc'e tests, where test execution and 
results aa.' predictable. 

It might lie inlen'siing to note that Redstone Software uses 
extreme Programming (XP). This is very apparent by tlicir 
willingness to listen to and supjXJrt dieir easiomers. Ihrough this 
inten.se supjxin of ihtar ctistomefs needs, tliey relea.sed several 
versions d' Eggplant—the tiiosn reteni on Ix^ing version 1.3 in May 
2003. The remainder of this article will focus on Eggplant vl.3. 

The Eggplant software runs on your host Macintosh. This is 
the computer that controls ihc‘ te.st. Ibe software you arc testing 
runs on a separate computer callcxl the ‘System-Linder-Test" 
(SLIT), The SUT runs Virtual Network Compuler (VNC) server 
software. VNC is a rentoie display .system that allow.s you to view 
tlie desktop of the "server'' eompiiter on another compuler 
anywhere cm the Internet. Tlie VNC .sc'rver .software could Ik" 
running on another Maeinio.sh or it could be running un a Unix 
or Windows armpuier. F.gg[3ianL is able to connect to the SUT 
using the VNC server software. 

VNC originated from A'f^'f Uiboratories Cambridge's 
development of very-lliin-clieni ATM network computers called 
the Videoiile (see http://www.uk,research. 3 ttxoni/tile.htnil). The VNC 
viewer and server are hasiailiy software-only versions of this 
A FM Network Computer VNC is free and is distributed under the 
leiTns of the GNU Public License, Eggidanl incorporates VNC 
client software to give it hill access to the SUT GUI, keyboard, 
and mouse using any VNC server. Any VNC client Viewer” can 
display the desktop of any VNC server; however, to use Eggplant 
you’ll have to use the client that is part of Eggplant itself, VNC 
clients are available for every major OS including: vMac OS 9, OS 
X, windows 95/98/ME/2000/XP, UNIX (AIX, Soiaris, flJ^UX), and 
LINUX (see http://WWW.uk.research.3tt.corn/vnc/;). The Redstone VNC 
server, OSXvnc 1.2 (see http ://www. redstonesoftware.com/osxvnc/) is 
recommended for use with Eggplant because of fixes made that 
improve performance and increase stability. 


Dave KcUy is currently a Software Quality Engineer at Earthlink and has many years of software testing experience at Eartliiink, Hewlett Packard, 
Symantec and Xerox. FJe liiis worked and played with the Madntosli since 1984 and was one of the foiintling editorial board members of MacTuior 
Magazine (now MacTech Magazin^. You can reach him at dkelly^earthlink.nH 
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The seuip for running Eggpbni consists of just stalling up 
the 496KB OSXvnc application and starting the sender by 
clicking the "Start Server" liutton (see figure 1). Tlte OSXvnc 
application will need to remain ruinimg or \hc connection will 
l>e broken. You’ll also want to hide the OSXvnc application 
liefore running your test. 


^ Pi f"' OSXvnc 

^ Standard options-- 

Display nvmb«f 0 

f&rt S900 

Pa^sward 

Display name PearJocal, 

2 Atlow Display Dimmmg (input undirns;! 
_ APdw Machine t& Sleep 


^ Swap Mouse Bunons 2 and 3 
_ Start Server On Launch 


t i 

__i 

. 

0 Let clients decide 

Always share display 
^ Never share display 

2 Don't disconnea existing dferiti 

Q Dtsablc Remote Keyboard/Pointer 

;1_ Onfy allow local conneaions (reqvlre SSH) 

Server Running 

^ View Log ) f Stop Server ^ Su** > } 


f igure /. OSXtmc Interface 



Sfraighi 6 sewnd bHUitg fn<remenfs 


Detailed billing directly from Copsule Communications, o Covisto Company. 


Excellent rates on intrastate/ intralata/toll colls 
and international colling with no term contract. 


Toil Free (800/888/877/866) service, 
same low per minute rate for incoming calls. 

10 cents per minute calling card. 


Quality uiectronk ond telephone customr support. 
No oioothly billing fee if you sign up for AUTOPAY billing 
option or if your bill is over $20.00 eoch month. 


Although the real testing happen on the SIJT, ihc host 
Macintosh is where die action is. When you open Eggplant the 
first thing you’ll want to do Ls connea to the SLIT, if anything 
else just so you can see how it works. After entering your license 
you’ll see a wamlow that prom]>ts you to establish a connection 
with a VNC sender. You can connect with the IP address, pon 
and password of the Siri' U is also possible lo ionnect using IP 
over Firewire or through an SSH connection. 


[ @ O O Establish Connection 

ftemore Host Of fP: Port. Password; 

10.20.0.81 5900 

T,. Use Secure Connection tSSHf 

r'i- 

^Sutus.... 

■jCi. ,y', . 

^ y ■: ___ _ _ 

Cancel ) ( Connect"^ 

L.' 

figure 2. Hggjdant connection mndow 




fIVOJE SLOO fi&g fee et drtir^ wten yogr A/f h mdif S20M for dl mn-kiteptty mtomm.) 


vrww»l0W€osfdialinff, com 
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Once the connection is established, you see tiie E^^fplani 
monitor and can conirol the SUV. ITie live remote screen in 
Figure 3 shows the desktoj} of the SIJT. 



Hgure 3 l^ggpianl Remole Screen meujar 

At this point, the VNC viewer can only ctrntrol the retiiote 
SU*l' and capture images. Tliai inighi t>e useful for some things 
but yon1l need to create a script in order to l^egin writing a lest. 
You start by creating a suite. When a new suite is created, 
Eggplant creates a directory structure to store ihe scripts^ images, 
and log flies pertaining to that suite. The suite window in figure 
4 is used to acces-s all of the features of the suite. 



f N€W 3 . ! ■. fttin O pgn 

4 Eggfflani sitiie miuiow 

Now for die fiean and sonl of the Eggplant... capturing an 
image. Once you open a new script you’re ready to start 
capturing. Building test scripts is dependent on being able to 
capture images through the viewer window\ Without capturing 


images, there isn’t much iliat you can do. 

The viewer has two modes, Capture Mode and Live Mode. 
Egg|>lani Stans out in live mode wliere you c'^in see and control 
wliatever goes on with the SUI*. By selecting “Enter Capture 
Mcxle”, you are able to select a rectangular seaion of die SIJT’s 
screen through die Eggfilani viewer, along with a hot spot, 
represented by a red crosshair (see figure 5)^ The hot spot 
represents the point that will be clicked when the script is run. 
The rectangular .seciion is the area dial will be captured as a 
snap.shot. After selecting die image and setting the crosshair to 
the point yon want to click, you can choose between stanckird 
commands dial will move the mouse and click or type text on 
the SUTs screen. Tlie standard commands that can be used are 
Click, Doubleclick, MoveTo, Dmg, Add Image, Wail, WailFor, 
Ty]>cText and TypeCommand. Tliese pretty much cover 
anything you will need lo do to test your software. 



Figure 5 icon selected and ready to capture 

After selecting your image, setting the click point, and 
selecting a command (example ‘‘Doubleclick"), Eggplant will 
add the image to the suite's set of images and add liic command 
to die script. For this example, this line would be added to the 
current script window: 

Doubleclick '‘ijnflgeOOOL” 

Meanwhile, the image is added to tlie suite’s images as 

in figure 6. 

f#ee _ mytest.suite 

_ f Scripts I Images | Rcsiilts | Schedules f Help err ] (j^) 

Image Name ---— 



(Add FotdeT) f Delete ) 

A 
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figui'e 6 suite images 


Alter capturing a secjiience of images/commands, you am 
go l>atk and eMablisli your iniliai setup conditions and run ihc 
script (or select a portion of the script to run). The viewer screen 
is compared to the siived image for each command and if it finds 
a maicii, liic command is executed. If it fails, the failure is stored 
in tlie suite's Results log. A log Is stored Ibr eacii liiue you run 
the script. During execution you can also log your own results 
from the script. 

It sltoLild lie apparent that the key is having the saved image 
match the captured image when the script ams. Eggplant does 
a great job of finding the correct image on the SUT's sc reen, but 
there are certain circumstances you must be aware oh For 
example, if the desktop background looks like a solid 
backgrounch hut isn’t railly a solid background, then llie image 
won't lie found if it Ls not exactly where it was when tile saved 
image was captured. The solution tlien is to make sure that the 
captured images are over a rail “s^ilid” backgniund. Also, ii is 
helpful to only ca[>ture the minimum that is required to identify 
the image l^ing compared. For example, it may only lie 
necessary lo capture the text of an image, or maylie just the 
center portion of tlie image. It only needs to lie enough to lx* 
identified as a unique image. 

Eggplant is very forgiving w'hen matching captured imagc.s. 
When images arc ca[)tured, Egg|ilant attempts to automatically 
detect the right setting for color matcliing. In most cases it 
defaults to “'Iblemnt" which means that it will allow small 
variations in the color to lx accepted. The “Precise" setting will 
look for a more exact matcii in the colors. 'I'heo tliere is the 
special “Pulsing" setting that allows color marching even when 
the color is a pulsing Mac OS X Aqua btiUon. IPs a gtKxl tiling 
tliey included these color ntaiching options so images, such as 
pulsing buttons, could be matched. 

Ln Seakcu ot’ niii **10001 ” Alttomahc testing tool 
It will help if you know what youTe looking for in an 
auromaric testing tcxyl. Regrettably, there isn’t much available for 
Mae OS X to ctympare with when looking for automation tools. 
It would still be worthwhile to know' what you want the test 
environment to provide and what you’re going 10 have to add 
to it to make It work for y<ju. The following is a short list of 
“.stuff to look For in test autoirmtion software and comments 
about how well Eggplant doe.s in eat:h of the areas listed. 

■ Will die test tool interfere with the software under tesr':^ llie 
VNC server on the SUT is not very intrusive stj you ll hardly 
even know it's there. You'll have to know your system under 
test well enough to know if a VNC serv'er would have a 
truiteriai impact on it. 

Eggplant relies on an IP connection. If your software makes 
clianges to network senings Eggplant’s connection with the 
SUl' could be broken. 'Itiis behavior needs to he taken into 
account when writing MTipis. 



Call: T-8()B“878-8523 Email: info@Ungosgs.coih^ 
Fax: 1 -503-419-4873 Or visit: www.llngosgs.c«m 
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needs and providing excellent customer service. 
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Applications? 
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• Can the test be controlled by scripts? Eggplant has a built in 
test scrip! language called SenseTalk. Sensei a Ik is a 
liypcrTalk-like language. The language is tjuile powerhil so 
you should be able to do imny of the things you need to do. 
The scrip! Ls run on the hosr Macintosh (not tlie SUT) so ail 
of the local coiTiniands refer to tlie host. For example, you 
can read/write to a local disk file (you might do this \o record 
s<>ine rest results or gel data for a test from a file), but the file 
must be available Lo the host eomputer If you need access 
to the SUT's files, there is an approach that may be 
acceptable. The workaround is to turn on file sharing on the 
SIJT and mtjunt the SI IT’s disk on the host compurer, 

• Can scripts lie captuied or do I have to modify scripts after 
capturing them to make them work? Since irmiges are an 
integral part of the commands it is nece.ssary to capture the 
images that will be compared. Yt>u cannot just slait Ly[)ing 
without also capmring an image. Some automation tools will 
claim that all you have to do is capture your script and then 
run it and you’re all set. Eggplaii! is really vay differeni 
because you are not capturing your script as much as you are 
c'apmring images that the script will use. Even with Eggplant 
scripts dtjn't write themselves (it is wishful ihinking when 
any company claims their tools will write tlie scrifits for you). 
With Eggplant, the process of waiting the scripts includes 
creating the images tlial will be used lo compare against 
W'hen the script runs. iTirtunately, tliis process makes it very 
easy to get the script up and running, 

Redstone Software makes the claims ‘ Manual te.st-oriented 
commands allow the nt>n-programmer to tjuiekly create 
scripts. Eggplant also offers the flexible and robust SenseTalk 
scripting language and the ability to test multiple application.s 
and platforms^, ’'Eggplant interactive script development 
simplLfie.s test automation" and SenseTalk scripting language 
provides high ease of use and iiowertul capabilities”, Linlike 
other autoniaiic f«)ftware test applituiions, ihey make no 
claims that the script can be captured and run without 
mcxlihcation. There will be a certain amount of script waiting 
Lo gel your tests up and ainning, hut as they elaim, Eggplant 
simplifies script development. 

• Can scripts he reused? 'lest scripts can call other test script.s. 
In this sense, libraries” of .script.s can lie wTitten to be lused 
over and over. In addition, scripts Ixfinnging to other suiics 
can be called by specifying them in the I lelper Suites list. 

• Can scripts lie sc’hetluled to nm at a certain time? Ilie scheduler 
can .setup a selectcxl batdi of scripts .so tliai they will mn on 
specific SlT's, but you are not able to set up a specitlc time for 
a script to run. You could set up a script that checked the rime 
lx,Tore it did anyiliing iliough. RecLstone recommends use of 
tile cron function to schedule tests. Hie bLiicli of scripts can 
also lie ‘\schedulecr to repeat however many rimes you ,specify. 

• Can .scripts be easily printed/dex umented? Yes, scripts can be 
printed. However, images eannol be printed from the 
Eggplant application. Ihe images are stored with the suite as 
.tiff files, and those can easily be primed if necessary. 


Additionally, .scripts can contain couimenls to further 
document what is being done. 

• Is diere a test infrastructure in place? Not completely, 'I'he test 
suite environment of Eggplant includes a script ediior, image 
list (showing images included in the suite), results list, script 
scheduler, and Helper Suites list. Eggplant could be 
improved lo include a better debugging environment, the 
ability to link test requiienients to tests being run, and an 
expanded capaLiiliry to keep track of test results. 

• Is there a inechuni.sm in place to keep track of test status? The 
Results tab is actually a very nice system for keeping track of 
test status. Building a test logging mechanism can lie a very time 
t:onsuming task. Eominaiely, w'itli Eggplant you don’t nml to 
build any tiling, and the logging Ls built right into ilie script 
language. Untbitunately, there isn’t a way to print ilie results 
from within the Eggplant appliaition. Btii, Ibnunately, the file is 
stored as a plain text log file tliat can lx: easily printed. 

• Is there an extm cost per user? Can multiple tests he run 

concurrently? If you want to nin multiple te.sf streams against 
different SUTs at the same time, liien tiiat requires multiple 
licenses. I’he aiiTent pricing scheme fbt^ multiple licenses on 
a single liost is as follows. Tlie base license aliow^s execution 
of tine Eggplant lest stream for A .second test .stream 

costs $1,700 and the third test stream adds $830. For $3,930, 
one system can execute* three different Eggplant test streams. 
Four or more concurrent slreajii licenses are $423 each. A 
lower end Mac cun easily handle three streams; higher end 
Macs cm of course am more. What many users do is to use 
one Mac as an Eggplant execaiLion .system and have licensee 
on other machines for script development. 

Hie Eggplant pricing is based on the numlier of test streams 
[leing nin with no additional chuigefor the number, location, 
or tyjie of sysieiiis-under-test. 

• Is there any debugging capability built-in? Although there Ls 
no ability ro add breakpoints, any portion of a script can be 
am at any time by selecting it and clicking on “Run 
Selection” in the script editor window. 

Summary 

Eggplant is a fine application. 'Hie really cool thing alxiui it 
is that it can nin rests on multiple platforms (all you need is the 
VNC server for the SIH you're testing on). Please don'i think iliui 
Eggplant is for software testing only. Develoiiers can automate 
the build process. Systejn Administrators using Eggplant can 
automate server maintenance. Any refieriiive ia.sk is a candidate 
for automation. Hiis Ls tlie fir.st really u.sable aiitoinatic softwai e 
tool that has been available for Mac OS X. It i.s very depressing 
to hear other companies tell you “Sorry, we don’t .support the 
Mac". Well, this changes everything liecause now there’s a tcx)l 
tliat WTirks with Mac OS X. 
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by Tim Monroe 


Revolution 


Developing QuickTime Applications with 
Revolution 

iNTRODLiCnON 

Rei/olution a software development environmunl 
written and published by Runtime Revolurion Ltd., a 
company based in Edinburgh, Scotland. Revolution is a rapid 
a pp I leal ion development (RAD) tool that can build 
applications for a number of operating systems, including 
Mac OS X, classic Macintosh OS, Windows^ and several 
versions of Linux and UNIX. In this article and the next, 1 
want to take a look ai using Revolurion to biiikl applications 
that can open and display QuickTime nuw ies. Accordingly, 
well limit our attention to using Revolution on Mac OS X and 
Windows systems. 

As usual in our recent articles, our goal is to build a multi- 
window movie playback and editing application. Let’s call this 
af^plication RunRevVeez. Ideally^ the movie windows dLsplayed 
by RunRevVeez slumid Ixj indistinguishable in appearance and 
beliavior from movie windows displayed by our other sample 
a[)plicatit>ns (such as the C-based application QTShell or our 
REALhasic application BasicM(jvie). And, ideally, RunRevVeez 
should be able to invoke any of the thousands upon thous?ind.s 
of QuickTime APIs. 

I'm happy to repon that Revolution performs quite nicely in 
both regards. It's extremely easy to use Revolution to open and 
display QuickTime movies, and to get them to Ixrliave as 
expected. Revolution provides a reas(jnahle selection of built-in 
command.s and functions for working with movies and movie 
properties. And Revolution provides a meclianism — u.sing plug¬ 
in ctxle modules — to access features of QuickTiitie tliat are not 
already built-in to Revolution. 

In this article, wee'll see how to set up a new Revolurion 
project ft>r a QuickTime player application. We'll add an 
About box to the application, and we’ll see how to create new 
movie windows and load movies into them. We ll create the 
a[>()licalion's menus and add executable code to a few of 
those menus. By die time we reach the end of this article, we 


should have a pretty good understanding of what it's like to 
create a simple application with Revcjluiitm and of how to 
work with QuickTime movies in that application. And 
eveiything we do in this article should work as well on 
Windows as it does on Macintosh. 

In tfie next article, we'll concentrate on implementing 
those features of RiinRevVeez that are not at all Cor m>L very 
easily) supported directly by Revolution. For instance, 
Revolution does not currently provide any methods or 
commands for editing a movie (cutting or copying Uic movie 
selection, pasting a previous cut or copy, and so forth); but it's 
ea.sy enough to write a plug-in module lliat supports these 
aqxtbilities, and it's easy to acce.ss that module from within 
Revolution code. In fact, wTiling and calling Revolution plug-ins 
is so easy that 1 can't imagine any serious programmer not 
wanting to use them a.s a matter of course. So it will l>e good 
to take a careful look at this technique. In that article, well 
focm primarily on develo()ment on Mac OS X, 

The current released version of Revolution is version 2.0.2, 
and that’s what Eve ttsed throughout these articles. Tliis 
version incorpcjrate.s a large ntimher of improvements over 
previous versions. 

RjiVoumoN OvTRvnw 

Revolution, like any good RAD tool, tmifies the 
development of an application's user interlace and its cxecutable 
code within a single environment. User interface elements (such 
as biinons, scroll bars, text-edit fields, fX)p-up menus, and so 
foitli) are objects that can be placed into windows and dialog 
l^oxes; these t>bjeci.s liave propenies that we can gel and 
(usually) also set. We do this, and other operations, by attaching 
code to objecLH that Ls executed when particular cvenLs occur to 
tltose or otfier t>bjeds. Revolution is not event driven, however, 
at least in the classic Mac sense of event-driven programming 
that involve^s a global event loop. Riither, Revolution is tmssage 
driven: all executable axle is contained in message handlers that 
are attached to ol^jecls in the application. There are, for instance, 
start-up and open messages that are sent when a window, dialog 
[k)x, or even the application itself is opened. 


Tim Monroe ts a member of the QuickTime engineering leaiii at Apple. You can contaa him at monroe^maderh.tom. The views expressed here are 
not necessarily shared by his em]>loyer. 
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So far, tliis is part of any standard RAD diett it is not 
terribly unlike the programming mmiel we saw in AppleScript 
Studio or RKAl-basic (a>vered in earlier QuickTime Toolkit 
articles). Revolution is interesting in several ways. First, it 
uses a sosralled fourth-generat ion la nguage for its message 
handlers. This language is called Tramcripi and is a dear 
descendeni of the HyperCard family of languages, In 
Transcripl, there are act explicit type dedamtions; the values 
of all variables are treated as strings but are coerced to other 
typtjs when necessary. For instance, we can add two values 
Icjgether like this: 

put 8+11 intu mySum 

After this ccxle is executed, the variable mySum contains the 
value “19" (a string). To concatenate two strings, we use the “^4" 
operator, like tliis: 

put & 6i 11 IntQ my Sum 

After this line of ccxle is executed, the variable mySum contains 
the value ^811", 

Revolution is interesting and distinctive also in the bask: 
vocabulary it uses to describe the application and its 


inieractions with a user, (Again, this is a holdover from 
HyperCard.) A window is a stack. Every application has one 
maimtack, and all other stacks in the application (that is, all 
other windows and dialog boxes) are substacks of the 
inainstack. Typically the mainstack .serves as the applicatiorTs 
main window. For dexttment-based applications (like our 
sample application RunRevVeez), there might however be no 
such main window; in this case, it is .still useful to have a 
mainstack, since me.ssages targeted at a subs rack are 
redirected to the inainstack if the substack does not contain 
an appropriate message handler In this case, the mainstack 
can just be invisible. 

Stacks contain cards. A card occupies the entire content 
area of tlie stack that contains it. Cards, in turn, contain conlroLs 
— which are the basic user interface: objecis like buttons, scroll- 
bars, etc. A .Slack can ctjnuiin more tiian one oard, and a atrd 
can contain more than one control. (Only one nird in a stac^k 
can be visible at a time.) Controls can lx grouped, for easy 
reference'. For our purposes, we'll need to work with only one 
group of ccmtrols, the menu bar menus. 

The PROjLcr 

Let's get started building our movie playback and editing 
application, KunRevVeez. First, launch Revolution. Alter the 
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splash-scTeen disappears, two windows appear, a hmk 
palette (Figure 1) and an applicaiion browser window 
(Figure 2). The applkation browser currently shows no 
stacks in the application. 
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figure 1: We iook fialette 


# Q 0 _ Appll mMon erqw$«r 

Ham I Hum | lb [sui^LJau 


Select i card 



Figure 2: Ihe application hnm^er 


The tools palette shows icons representing a number of 
controls that can he placed into cards, including push 
buttons, labiied buttons, check boxes, radio buttons, texi-edii 
fields, list boxes, scrollbars, pull-down and pop-up menus, 
and images. Of particular interest for us in this anicie is the 
player object in the lower-right corner (%vhose tool tip is 
“QuickTime Idayer"*). 

'I'he top two icons in the tools palette do mjt represent 
conirols. Instead, they indicate which mode the IDE is In. 


When the arrow' is aaive (as in Figure 1), the IDE is in edit 
mode: we can add stacks, place controls into cards, and edit 
the executable code in a message liandler. When the little 
hand icon is active, the IDE is in browse mode: we can run 
scripts and interact with the objects in a card. By entering 
browse mode, wc can test out the operation of our stacks 
and scripts without having to build the application or leave 
the IDE. 

Adding Stacks 

The first thing we need to do is add a new mainstack to llte 
application. Select “New Mainsiack" in the File menu. A new 
empty stack opens, as shown in Figure 3* 

@ 6 Q__Untitled 1- 




figure JL- 7he new, empty tmiimtack 

In earlier articles, we used the default new window- 
provided by the programming envirt>nment us a temj>Iaie for the 
multiple movie windows our a pp I initio ns could open, and 
indeed ifs tempting to just click ilie player objet r icon in the 
iCK>ls palene and then click-dmg a new movie player in the new 
window. With Revolution, however, we Ye going to use a slightly 
different architectufe in our application. It will he easiest to add 
another stack to the application and to use tliai subsiack as the 
template for our movie windows. 1he m;iinstack, for the 
moment, will serve merely tt) hold global handlers (as 
mentioned briefly alxwe). 

Ixn’s t'hange the name of the mainstack. Select the “Stack 
laspcxtor" item in die IDE's Object menu to open a propertm 
inspector like the one shown in Figure 4. 
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O stack "Untitled 1*. ID 1002 


' Basic Properties 


3 


® 


Name Untitled 1 
Title I 


Controls [default 


Shape 0 


Main stack ^ Untitled 1 


ID 


M Visible 
^ Minimized 
Q Open minimized 

0 Underline links 
0 Format for printinp 

5! Buffer display 
0 Purge stack on close 
0 Purge v^indow on close 

0 Can*t delete 
0 Can't modify 
0 User can't abort scripts 


Fijfure 4: A propenies 

Set ihc Niime fiekl to '"KunUevVee?:”; notice that the name of the 
mainstack in the pop-up menu als^> changes to ‘‘RunRevVcez”. 

Next let's take a look at how we can attach a message 
handler to tlic mainstack. In the prEspcitics inspector, press the 
button with the triangle icon near the top of the window; lliis 
pops up a selection menu. (Sec Figure 5.) Select the “Edit Script" 
item in that menu. 
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Shape fo 
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0 Open minimized 
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^ Buffer display 
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O Rurge window on dose 


□ Can't delete 

O Can't modify 

Q User can't abort scripts 



Figure y: Ihe sclectkm menu 


s^t the defaultcursor to arrow 
il the QWersion is "0,0" then 

answer error "QuickTime is not Installed! " 
close stack "RutiRcvVee^" 
end if 

end preOpenStack 


Notice that a message handler is deiiniited by llie keywords 
and ^‘end", each followed l)y die name of the message. The 
preOpenStack message Is sent to a card before the card is 
drawn in its stack on the screen. In our case, we want to 
perform any one-time initialization of the mainstack and the 
application. We set the default menu liar and the default cursor, 
and we check to see wliether QuickTime is installed. The built- 
in funaion QTVerston returns die version of QuickTime that is 
installed on the system. If QuickTime is not installed, then 
QTVersicn returns the value As you can see, we look for 
that value; if‘we find il, we use the answer command to display 
the alert box shown in Figure 7. (The error keyword indicates 
that we want the error icon to be dis]>layed; other choices are 
information, question, and warning.) 


o 


QuickTime Is not insutted! 


m ^ 


Ai this point, a scrip! ediior window will appear, us shown in 

Figure 6, 


9 Sertpt Editor * slack '‘ftunRjevVeez“ 



Figure 6: 'fbe scripl edUor window 

We can add message handlers in this window. For now, let’s 
type in the code shown in Listing 1, 


Listing 1: Opening the application 

on pcsOpenStack 

set the defaulimenubar to the name of 


pndlpcnStack 
group "HainMynu" 


Figure 7: Hiding the controller bar 

ir QuickTime is iiol iivaikihle, we quit RunRevVeez by 
closiii}* the mainstack, like so: 

close stack ‘'RunRevVeeii** 

In general we refer to stacks and objects by name. 

Setting Up the Menus 

Let’s move next to set up our applicadon's menas and 
menu bar With Revolution, this is a bit trickier than with other 
RAD tools, owing laigely to tlie fact rhat Revolution wants to 
target a variety of operating systems. Menus in Revolution are 
buttons, and the menu bar is a group of buttons. Each stack 
can liave its own group of buttons — that Is, its own menu 
bar On .Macintosh operating .systems, tfiis isn’t really what we 
w'aoT. So we’ll create a single menu bar associated with the 
mainstack and then set the appiicaiion's defaultmenubar 
property so that all the stacks in our application use that menu 
ban (Look again at Listing 1J 

To create our menus, select ‘'Menu Builder” in tlie Tools 
menu. The tnenu builder dialog box shown in Figure 8 appears. 
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Figure 8: The menu builder dialog box (empf}0 

Click tJic New button. In the dmlog lx>x tliat ihen appears 
(Figure 9), the name to *‘MainMenu”. Notice that three 
menus are already included in the new mejiu bar 

Create a New Menu Bar 


In stack: 


RunRevVeev 


D 


Menu Bar Name: | MalnMenuj 
Menus: 



Figure 9: We menu naming dialog box 

When we click the OK huiion, die menu builder dialog box now 
contains die duee default nienus. Click the ^Set as Menu Bar on 
Mac OS" check box (as in Figure 10) to get the proper l)chavior 
on Macintosh systeras. 
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(9 0 . Menu Builder: Main Me rtii (Stack; "Run RevVeev'*) 



Figure 10: The menu buiklerdiaiog to (default) 

The coasrmction of nienii,s is reasonalily siniighilnwiird. 
Using the eonirtils in the menu builder dialog box, add the 
aj>propriate menu items (ttjgeiher with the usual kt7hoard 
shortcuts) to the File and Edit menus. Add a new menti, the 
Movie menu, and add two items to that menu: "Hide Controller 
Bar" and "liide Speaker Button”. In the tielf^ menu, add the item 
"Alxmt RunRevVecz”. Wlien weVe done, the menu builder 
dialog box will look something like Figure 11. 


0 @ ; Menu Builder: MainMenuBar (Stack: “RunRevVeez" 



Now we need to add some code to handle the various 
menu items. In turn, select each of the four menus in the 
menu builder dialog box (Hie, Edit, MoAue, and Help) and 
dick the ^*Auto Script'" button. Each time we click that 
button, Revolution creates a default script for the selected 
menu. For instance, Figure 12 shows the default script for 
the Help menu. 


S @ 9 Script ErirtDf - biiitQn of grovp "MflinMeouiar" of Cifd id 1002 of soiclt "Ru 



figtire 12: The Help niemt script (default) 

Notice that the Menu Builder has created a menu Pick message 
handler, replcie with the necessary switch and case 
statements to handle all the hem.s we added to the Help 
menu. All we need to do is add code to liandle those items 
in I he appropriate manner in RunKevVeez, we'll simply 
ignore the IIel[) item in the Help menu. To handle the “About 
RunRevVeez” menu item, we can insert the code in Listing 2 
inu) the menu Pick handler. 

Listing 2: Haudiiiig tlie About menu item _ 

QicniiPidt 

case "'About RunRevVe^a" 
open stack "'AhoutEox" 
set visible of stack "AboULBox" to true 
break 

end switch 

lliis tells our application to c>f>en a stai’k named "AboutBox” and 
then to set its visible property to true. 

It I urns out that Revolution is smart enough to move the 
“About RunRev'Veez" menu item from the Help menu into its 
proper place in the Mac OS app)ialti^m menu, as shown in 
Figure TJ, 


Figure H: 7he memi builder dialog box (Jmal) 
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"WiV/iou/ a doubi^ the Premiere Restiuree Editor 
for the Mac OS ... A wealth of time-saving iools.^ 

- MacUser MagCLzine Eddy Aivards 

"A distinct improvement over Apples ResEdiL ” 

- MacTech Magazine 

“Every Mac OS developer should own a copy of Resorcerer. ^ 

— Leonard Rosenthal, Aladdin Systems 

“Wthout Resorcerer, our localization efforts would look like a 
Tower of Babel. Don't do product without itr 

- Greg Calanos, CEO and President, Melrowerks 


*'Resorcerer's data template system is amazing.'’ 

- Bill Goodman, author of Smaller Installer and CompacL Pro 

""Resorcerer Rocks! Buy it, you will NOT regret iV 

- Joe Zobkiw, author of A Fragment of Your Imaginafion 

“Resorcerer will pay for itself many times over in saved time and effort” 
— MacUser review 

“The template that disassembles PICT’s is awesomer 

- Bill Steinberg, author of Pyro! and PETools 

“Resorcerer proved indispensible in its own creation!” 

- Doug McKenna, author of Resorcerer 
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• Most editors DcRcz directly to the clipboard 

• All graphic editors support screen-copying or partial screen-copying 

• Hol-Unliing Value Converter for editing 32 bits in a dozen formats 

• Its own 32-bit List Mgr can open and edit very large data structures 

• Templates can pre- and post-process any arbitrary data structure 

• Includes nearly 200 templates for common system resources 

• TMPLs for Installer, MacApp, QT, Balloons, ApplcEvent, GX, etc, 

• Full integrated support for editing color dialogs and menus 

■ Try out balloons, ietb’s, lists and pop ups, even create C source code 

• Integrated single-window Hex/Codc Editor, with patching, searching 

• Editors for cursors, versions, pictures, bundles, and lots more 

• Relied on by thousands of Macintosh developers around the world 


■'lb order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website**, 

www.mathemaesthetics.com 
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Hide RunRevVeez 8SH 
Hide Others x:3gH 
Show All 


Quit RunRevVeez 3€Q 


figure 13: Ihe Application menu of RunRei*Va^ 


Adding the About Box 

Of course, our application does not yel ctiniain a stack 
named **A[x>iitBox’\ So let's add one. Select the menu item "New 
Substack of RunRevVeez" in the IDE’s File menu. A new stack 
(that is, window) will appear. Open the propeny inspector for 
the new stack and set its name to “AboutBox” and its title to 
"Alx)ut RunRevVeez". 

Next, click the "magic wand" icon next to ihe Controls Field; 
a sheet will slide down allowing us to select the desired controls 
for llic windows title bar, as shown in Figure l4. 


0-0 itack "AbQutRox", ID 1002 


Select a set of title bar controls: 




Cancel ^ | 016 ^ 


Q Purge stack dii dose 
C} Pu rge wind aw on clos e 

O Can't delete 
Q Can't modify 
□ User can't abort scripts 


Ix^t's select tlie sei of controls with the fewest buttons; since we 
are currently building RunRevVeez only for Mac OS, we can 
select the third set from the top. Click OK. 

Select the "Colors & Patterns" item in the pop-up menu in tlie 
properties inspeaor for ilie Alx)ut box and then chtxxie the Aqua 
striping for the background pattern. Then select the “Size & 
Position" item and m the size of the stack as shown in Figure 15- 


O Q stack "AbomRox", ID 1002 
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Resizable 
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figure !%* 7heAl:x)Ul box ^ize settings 

Now we need to add items to the About 1X3X so tliat it has 
the standard appt^anince shown in Figure l6* (Notice tliai Fve 
added a one-pixel border arotmd the image; as well see, this is 
easy lo do, and it makes tlie lx>x look a bit nicen) 


© _About RunRevVeez 

A QuickTime movie ptaver application 
built with Runtime Revolution. 

© 2003 by Tim Monroe 


OE3 



Figure !4: 'fbe umdow iilie bar amiroi sheet 


jFigurt' 16: 7heAfx)Ut box of RunRetJVeez 
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First, click the Image tool in the tools palette and then click-drag 
an image well in the About box stack. Set the size of the image 
as shown in Figure 17. 


0^0 image '*lmaigg 1*, ID 1003 

' Size & Position ^ f] 


0 

0 , 


Q Lock size and position 
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23 
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Top 
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JB 
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hi* 

i::) 



SOFTWARE 

LOCALIZATION 

MAOE 

easy 


1.1._ I 

Mumbef 


Fiiiure J 7: The penguitt hnage size settings 

Set the image lUe to the standard penguin image, penguin.pet. In 
the properties inspc‘ctor for llie image, turn on the "Show 
Btjrder'’ pro|:)erry but turn off the '^'lliree O'* option for that 
property. Finally, set the border width to 1. Set lire i(X)l lip lor 
the penguin image to "Keep tire lawyers Imppy!” 

Apparently, the Revolution license requires any applications 
built using it to display the Revolution logo at some p<iini. (Hey, 
I'm not a lawyer, this might not be strictly correct.) So let’s 
add a second image to the About box; this iimige will be initially 
invisible but will become visible when we dick the penguin 
image. Add a second image using one of the logos distril>uted 
with the Revolution IDE, say "Runtime smalLpcF. Make that 
image initially invisible. Open the script editor for the penguin 
image and add the handler shown in Listing 3- 

listing 3: Handling clicks on tlie penguin image 

niouscUp 

on tious^ap 

set the visible of me to false 
sc?t the visible of inage "levlton" to true 
end mouseUp 
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Once the user lias clicked tlic penguin image, the About 
box will look like the box in Figure 18. 


I ^ Q Q About RunRevVeez 

A QutckTtme movie ptayer application | 
bulk with Runtime Revolution, | 

® 2003 by Ttm Monroe | 

1 

I 


Figure 18.^ We About box ivith the Hemlution logo 

Just for fun, let's configure the Revokilion icon image that 
clicking it will rurn it back into the penguin image. Of course tlie 
script would look like the code in Listing 4* 

Listing 4: Handling clicks on the revolution logo image 

mQWixUp 

on mouGeUp 

set the visible of me to false 
set the vistble of image "Pen^irln” to true 
end irovjaelJp 

The last control wc need to add to our About htjx is the OK 
button. Select tlie iiutton icon in tlie tools paleitc and Uien click- 
drag a biitTon of the appropriate size in the appropriate .spot, in 
the properties tnspecior, set the name of the hmron to OKButton 
and tlic ]al)el to OK, Check the “Default button” check box. 
Finally, we need to script the button so that clicking it causes tiie 
About box to disappear, 'I'his is easy enoughs add a mouseUp 
message handler to the button with this single line of code: 

close this fitack 

Our About box is now complete. IFs time to move on to 
consiniciing a movie window. 

RiivoLirnoN's Playo Onji-cr 

Revolution provides a player object (oi; more l>rief!y, a 
player) that we can use to display Quicklime movies in a card. 
There are a large nunilxT of built-in messages and propciiics 
a,ssr3ciated w^ith a player object, and we can also define custom 
me.ssage.s and properties. Of particular interest is the 
movieControllerlD pro[>eny, vvhicli is a pointer to the movie 
controller associated with the movie ixing dis[dayed in a player 
object. As well see in more detail in the next article, we can use 
this property Ui extend Revolution's QuickTime capabilities 
beyond tlie built-in iiicthods and pro^xTiies, 

These built-in properties include a number of properties 
associated with norma! linear QuickTime movies: 


currentTime, ttmeScale, startTime, endTime, paused, 
pfayLoudness, playRate, playSelection, trackCount, looping, and 
so forth. For QuickTime VR movies, Revolution defines a 
handful of properties, including: currentNode, hotspots, nodes, 
pan, tilt, constraints. 

Most of these properties are associated with numerical or 
Boolean values, but several of them return a list of values. 
Revolution provides easy ways to iterate through these lists 
looking for particular values. For instance, a player'.s 
mediaTypes property^ contains a comma-separated list of 
strings that describe the media types in a movie; This list can 
contain some or all of these words: video, audio, text, qtvr, 
sprite, flash. We can find movies with sound tracks, and 
operate up(m them, like this; 

if the mediaTypefi of player "MoviePlayer" contains "audio" 
then 

inc rc>!iTi:ant Loud ness 
end if 

Revokiiion also define.s eiglii messages that can be .sent to 
a player object: currentTimeChanged, deletePlayer, hotspotClicked, 
newPlayer, nodeChanged, play Paused, QTDebugStr, and 
selectionChanged. For present purposes, however, we won't 
need to write any message handlers for these messages. 

Adding a Movie Window 

LcTs begin by adding yet another substack to the 
main.stack. This new .substack will serve as a template for 
new movie windows. When the user decides to open a 
movie file, w'e'll clone this stack and load the movie into the 
cloned stack. In this way, we'll have ihe ability to open an 
unlimited number of movie windows, all sharing the 
properties of tliis substack. 

Name the new subslack '"MovieWindow”. Then add a 
player object to it by clicking on the QuickTime icon in the 
tools palette and then click-dragging in the new substack. (If 
you prefer lo use menus, you can seleci ihe Player item in 
the ’“New Contror hierarchical menu of the Object menu.) 
Don't worry about making the player exactly fill the movie 
window, as we ll take care of resizing the movie window 
when we load a movie into it. In tlie properties in.spector for 
the player object, .set the player’s name to “MoviePlayer”. 
Make sure that the Visible, Controller, and “Focus with 
keyl)oarcr check boxes are checked. More impotianrly, make 
sure that the Buffer check box is unchecked. (Checking that 
box would turn on the alwaysBuffer property of the player 
{j|)ject, which renders the controller bar ineffective.) Figure 
19 shows the desired properties. 



60 


RnvoLunoN 


MacTech • Seffemheh 2003 










Xserve 


C 11 # ^ “ 

"::miiiiiiimiii i 

i iiiiiiiinij 



S' 





■1 


Density optimized rack mounted Mac OS X Server 



UNIX-based Server Solutions from Apple 

Nearly half a terabyte of stoi^e per lU 
630 gigaflops of processing power 
Hot-Swappable drives 

Industry-standard lU rack-optimized design 


There has never been a better time to buy... 

Small Dog Electronics carries 
factory refurbished models too 
offered at substantial savings! 

(subject to availability) 



Small Dog 

Electronics 

www.smalldog.com 


1673 MAIN Street, Route 100. Wa[tsfiei_d, Vermont 


# Apple Specialist 















































































Q O Q ptoytr "MovtePtayer*, ID 1003 


f Bo^ic Properties 


0 


0 

© 


Name | MovkP^ej^ 
Source I ~~ 

Tool tip 


lU 


o Suffer M Viable 

0 ControKer 
Q CoritroUer toggle 
0 Focus with keyboard 


Time 
Start []^ 

Eod n 


IS 


:1s 




□ Hlifte selection 

O Play selection only 

Speed I I I ?? 

□ Loop 


Volume ^ 


n Border 
□ I-D 

Width rr 


100 




Figure 19: Thepkiytr ohpet properties 

Notice twt> tilings here. Firsi, the Border option is not 
.selecteci; since the movie window will ix: si^^ed lo exocfly 
contain the movie and its controller ban we don't want a Inirdcr 
around the mtivie. Second, notice that weVe left the Souax^ 
property blank. IF we wanted to Ofxrn a specrtlc: movie, we could 
specify its full pathname as the source. As usuai however, we 
want to give the user complete choice over which movies to 
open. So we'll need to specify the source movie 
programmatically in our .script. 

Opening a Movie File 

Now let's see how to open a movie file and display the 
movie it contains in a movie window. Obviously, we want lo 
add some code to the menu Pick handler for the Open menu item 
in the File menu. Revolution provides the answer file" command 
ifiat wc can u.se to elicit a movie file from the user; we c’an call 
it like this: 


answer file "Openi RunRevVeez" of type **Mof>VSVFl" 

This line of code displays the standard ftkM>pening dialog box, 
with the prompt string (here “Open: RunRevVeezO used as the 


title tif the dialog box; in this case, only mo\ie files and Flash 
files can Ik' .seiccled by the user 

When die user selects a file, the complete pathname of tliat 
file is placed into a special variable named “if*. We c^an make 
sure that the u,ser actually selected a file (and didn't just hit the 
Cancel button) by testing that it isn't the empty siring: 

if it <> then 

Anti we can save that full pathname for later ase by assigning it 
to a local variable: 

pnt it into savedFilePath 

Recall that we are going to make a copy of the 
MovieWindow substack to serve as a window to hold the new 
movie. We can do that quite easily- 

done stack ’^MovieWindow" 


Ihe new window is named “Copy of MovieWindow”, and this 
will also be the title of the new window^ if we don’t change it, 
A.S usual, we want the Title of the movie window lo lie the files 
hasename (the portion of ihe full pathname that follows the 
rightmost path separator). We cun get the liasename quite easily 
like this: 

set the itemDelifniter to 

put the lasr ftom of sttvedFllePath inio newStackMaine 

11 te itemDelimiter is the cliaracter that is used to delimit the 
chunks of a .string. By dcTauli. a hamlier's itemDelimiter property 
is set to the comma f %"), but it c'lm l>e reset at will. Here we set 
it to the slash character (**/”), which delimits the parts of a 
pathname. Once weVe execiUed these two lines of aTipl, the 
kK*^al variable newSlackName should contain the file's basename. 
We can Uien use that variable to set the name of die stack and 
the title of the new movie window: 

set the name of stack ’'Copy of MovieWindow" to newStacitNaiie 
set the title of stack newStackUauio to newStackName 

Now we need to assign the movie in the file we just opened 
to the player object m the stack we just created. We can do that 
by setting the filename property of the player object in dial stack, 
like this: 


set the filename of player "MoviePlayer" of stack 
aewStackNarae to savedFilePath 

The filename property can set to any full or partial 
pathname; if the pathname is panial, then it’s interpreted 
relative to the value of the defauKFolder global property. 
(When a Revolution application is launchec!, the defaultFolder 
property i.s .set to the folder containing the application; w^e 
can programmatically set it to any other folder we wish.) The 
filename property can also be set lo a URL. In RunRevVeez, 
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however, well always use full paihnanies, as returned by the 
“answer file" command, 

listing 5 shows our complete definition of the menuPick 
iiandler for the Open menu item. 


listing 5: Opening a movie file 

mcnuPick 

case ‘'Open*." 

answer file "Open: RunttevVeea" of type '‘McoVSWFL‘' 
if it <> "- then 

pnt it into savedFilePath 

“ get the base name of tlie file 
set the ItemDelimiter to */" 

put the last item of savedFilePath into tiewStackNamc 

create a new (ftovie window 
clone stack "MovieWindow" 

set the name of stack “Copy of MovleWitidtjw" to 
newStackNaine 

set the title of stack newSrackWame to newStackKame 
set the visible of stack newStackName to false 

load the movie Into the new window 
set the filename of player "HovlePlaycr" of stack 
fiowStackKame to EsavedFilePath 

*- set the size of the movie window 

sizeStackToMovie newStackNamo 

set the visible of stack newSrackWame to true 

set the visible of player "MoviePlayer" of stack 
newStackMame to true 

end if 
break 

You’ll notice tliiit we make die movie window invisible before 
selling its size and then make it vtsilile thereafter. We also need 
to make sure the player abject itself liiis its visibility state 
restored. 


Sizing Movie Windows 

The last thing we need to do when opening a QuickTime 
mt)vie is to resize die movie window so diat it exaedy cotilaius 
the movie at its natural size and the movie cxintroller bar, if 
present. In listing 5, we called the message handler 
sizeStackToMovie, which is defined in die mainstack. The 
definition is siraightforward and relies on the height and width 
properties of die player object (Listing 6), 


Listing 6: Setting the size of a movie window 

si^^eSmckToMuvle 

on siz^StackToMovle theStack 

put the height of player "MoviePlayer'' of stack theStack 
into wiudowHelght 

put the width of player "HoviePlayer" of stack theStack 
Into windowWidLh 

set the width of stack theStack to windowWidth 
set the height of stack theStack to viudowUeight 
set the rectangle of player "MoviePlayer" of stack 
theStack to Q*0>windowWidth*windowMeight 
end sizeStackToMovle 

We set the height and widdi of the movie window to the 
height and width of the player objea, which is set to the movie's 
natural dimensions when the movie is first opened. Then we 


There orders 
and Losers... 



www.prosofteng .com 


PROSO[F? 

engineering, inc. 


These products are only available for the Mac OS. so your 
Windows friends will still be losers, ,. 


©2003 Prosoft Engineering, Inc., All rights reserved 


.Skptember 2003 • MAt^Teai 







rc,set the rectangle of the player oljject so that its upper left 
comer is at the point 0,0 in the window's a>nienf area. 

Movie Playback 

The amount of ctxJe wt need to write in order to o}X‘n a 
QuickTime movie in a window on the screen is surprisingly 
small. We clone the MovieWindow stack, set its filename 
property to a patli elicited from the user and then resize the 
movie window to exactly contain the movie at its natural size. 
Once weVe done this, the movie appears, just like it sliould, in 
a window; Figure 20 shows a sample rmwie window displayed 
by our current version of RunRevVeez. 


© © Sample Movie 



figure 20: A sample movie window 

This window^ Itehaves exactly as we'd exped; we can drag 
j| around on the screen by grabbing its riile bar, minimize it by 
clicking on the yellow button in the title bar, and close it by 
clicking on the red button in the title ban We configured the 
window so that it’s not resizable, so the green button i.s inactive. 

Moreover, the controller bar functions perfectly, and 
keylx)ard operations (such as starting and stopping the movie by 
pressing the spate bar, or moving forward and backwarti by 
pRrssing the right and left arrow keys) work exactly as they 
should. In short, tor noniiai linear QuickTime movies and for 
QuickTune VR movies, Revt)lulion works flawles,sly as far as 
normal movie playbac'k is concerned. 


Ensuring Smooth PUtyback 

Prolilems arise, however, w^hen w^e open certain types of 
non-linear QuickTime movies, like movies containing wired 
sprites or zero-M)urce Qiitckdlme video effects. For instance, 
when we open the fire movie we created in an earlier article 
(""F/X” in Maclecb, Septemlter 2(X)1), well quickly notice that 
tlie Fire does not burn by itself, (See Figure 21.) A few flames 
sputter up tnitially and then the fire freezes (if thafs even 
possible). Oddly enough, if we open a linear movie and start it 
playing, the fire will join in and burn, Ixii only for as long as the 
linear movie is playing. Even more (xklly, if we open the About 
box, tlie fire starts burning, but (again) only for as long as the 
Atx)m box Ls open. 


@ © _ fire.mov 



figure 21: A non-hurmn^fire 

It's pos.sible rliat IVe got my movie stacks somehow^ 
configured Lncorrecily, bur I'm inclined to dfxibt that, given that 
we’ve used such siitiple and natural code to get to tills point. It 
seems mure likely to me tliai tlie Revolution runtime engine is 
for some reason failing to call MClsPlayerEvent or MCldle often 
enough to keep these non-hneiir movies playing. 1 dunno. 

nap[)ily, fhe About liox hehavior described above 
suggest-s a simple and apparcnLly effective workaround. 
Keep in mind that our mainstack is currenily empty, visually 
speaking. It's serving only to hold handlers for applicatkm 
stan-iip and wandow sizing. I have discovered that if we 
jdace a defaiih button on the mainstack, as shown in Figure 
22. then the fire movie and wired sprite movies behave as 
they should. Something about that pulsating button seems to 
wake up the movie controllers, I dunno. 
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Figure 22: Thv main stack with a button 

Of course we don’t want the maiaslack to lx* visible while 
our application is running, especially with its ttirobl>ing l>uUon, 
St> lei's just move it tmi of the way at application launch time. In 
the preOpenStacK mcssiige liandler we wrote e^trlier (see listing 
1), let's add one line at the bottom: 

set the IdCfition of fiiack **RunkevVeez” to bC9O0,3QOO 

Tills moves the stack sutltlciently tar offscreen that it shouldn’t be 
visible. 

As I said, this workaround seems to solve tlie problem 
entirely. There may be a l::etter solution to the original problem, 
but this hidden-mainstack-with-throbhing-button will do fine 
until we find that Ix^ttcr soIliIioh. 

Handling the Movie Menu 

Recall that we added a coupie of menu items to the Movie 
menu, one of wliich is supposed to toggle the visii>ilUy state of 
tlie controller l>ar. We can implement this item quite easily in 
Revolution by getting and setting the player object's 
showController property, as shown in Listing 7. 

listing 7; Setting tlie size of a movie window 

nanul^ck 

case "Hidfi Controller Bar'" 

if shftvController of player "KaviePlayer" of stack 
theTopStack is true then 

set, showController of player "MoviePlayer" of ntack 
theTopStack to false 

else 

set showController of player ^MoviePlayer* of stack 
theTopStack to true 

end if 

utsicStackToMovie theTopStack 
break 

Notice Thai we call sizeStackToMovie lo make sum diat the movie 
window is resized correctly to hold the movie and any 
associated contn)llcr f>ar. 


Listing 7 raises an interesting question: how did we figure 
out die value of theTopStack? RunRevVeez can have more than 
one movie window open at a lime, and we want to apply the 
menu item only to the frontmost movie window-. So how do we 
figure out which movie windf)w is in front of all others? 
Revolution provides tlie topStack function, which returns the 
frontmost stack window with the lowe.st mode. Sint:e the 
mainstack and the movie window .stack liave the same mode, 
topStack ougltt to return the frontmosi movie window. 

'Ihe trouble is, 1 could never get topStack to work quite 
right. Fortunaiely, Revolution alsf> provides the openStacks 
function, which returns a list of open stacks ordered according 
to their order on the screen. Tlie first eleuieni in this list is the 
frontmost stack, and we can read that first line like diis: 

put first line of the openStacks into theTopStack 

You can expect to see that line of code at the beginning of any 
liandlers for menu items dial apply only to a movie window. 
You will al-so often see the following line of code, which tests to 
see wlielher tlie frontmosi window' contains a player object: 

if exists (player •MovieFlayer* of istack theTopStack) then 

This allows os to distinguish a mtivie stat:k from the mainstack. 
G>nci.usion 

So far, so good. Revolution appears to lie a simple yet 
|X)werful environment for cR^ating af>plication.s. It provides 
suppon for opening and displaying QuickTime movies, and it's 
easy enough to get am application to support multiple open 
movies at once. We ran into a minor priyblem w'ith playback of 
some kinds of movies, but we alst> discovered a simple and 
effcx-live w'orkaround tf) that problem. 

Still, weVe got a fair amtyimt of work remaining in our quest 
to develop a multi-window movie playback and editing 
applictilifyn. We need to tackle the movie editing 0 [>enitions, and 
we need a way to track tlie slate of am movie windows so that 
we can enable and disable menus and menu items 
appropriately. For these enhancements, we need to move 
lieyond wiiat’s built in to Revolution and explore the topic of 
Revolution plug-ins. Well tackle all that in our next article. 

Credits 

'ihanks are due to Kevin Miller and Tuviah Snyder at 
Runtime Revolution Ltd. for their unllagging as.sistance in 
improving my understanding of Revolutirin. A very sjicdal 
thanks is due to Geoff Canyon of In.spirecl Logic, LLC, for 
aasw’ering a number of questioas ulxiut Rcvtylution. 

Tlie Runtime Revolution web site (http://www.runrev.com) 
contains a wealth tyf information about Revolution as well as a 
free trial version of tlie development environment. 
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REVIEW: CH 


By Matt Campbell 

Ch - A C/C++ Interpreter 


New possibilities for people who 
like C and Unix. 


First Look 

Given tlial C is ihe basis lor much of ihe programming 
behind the Mac, which now utilizes Unix as its sul)slruc1ure, C 
seems lo be the language that all Macs speak. If yoit're nut eager 
to dive into many different languages for different tasks, take a 
look at Ch. Ch expands the capabilities of C and makes it an 
interpreted language. Its tight integration with the Unix siiell 
makes it natural ior Mat' OS X. To those who are using C and 
are cc>m^bitallle with the command line mierfaec t>r arc willing 
to learn, 1 think you will discover Ch to be a useful t(K>l. Ch can 
help with shell programming, development, numerical 
computing, and learning C. 

Setup and Trying It Out 

Anyone wanting to give it a whirl ran get iltc Stamlard 
version of Ch for OS X, Unix, and Linux free. Not bad for starters. 
Clieck out die website at http://www.softfntegralion.com/. Go to the 
downloads page and register, after which yon will l^e sent 
tlownload instructions via email (mine came in a matter of 
seconds). After downlcxiding and installing the package, start tlie 
Tenninal applicatu>n in the Applications > Utilities folder and 
type ch “d. ttie <1 option loads die startup file, .chrc\ in your 
liome direciory. 'Uien edit this hie using vi and uncomment the 
line that starts with _padL Tliis leLs you run files on the command 
line without entering the current directory' patli, l>efore the file 
name. There's a little infonnation in the KhADMh file including 
directions to uninstall. If you like, Ch can even lx; run as your 
default shell. Using the Temiinal > ?referenix^s... menu, select the 
lujtion to execute this comnvind ut^>n crediting a tenninal 
window and enter /bin/clu Now any new shell you start w'ili 
automatically ntnnlng Ch. More dtRumeniauon vAti Ix" found 
in the /usr/lcx^l/ch/dtx"s folder from die command line f>y tyfiing 
oixm nienaitx.pdb I've Ixen using Ch for 6 mantles and C c-overs 
lots of ground, so Til try to give you the am down on most of the 
important features of Ch. Here it goes. 


Ch as a C/C++ INTFRPRETER 
At the simplest level, Ch is a C interpreten It is able to run 
C code without conifiiling. It does not need a projec't space or 
any of the other associated files that are usually created in the 
compile/huild/delKig/exet'uie cycle by most programs used in 
w'riting code. All that's necessary t.s the [)rogram tile. I’here are 
rwo levels in its ability to run the C language on the fiy. First, 
it will run C code Interactively from the command line, as a 
command interpreter, if you're still learning C, this is 
invaluable. When having problems with a particular siatemem 
or wondering about the output of a command, it can be 
entered on the command line to lesi liovv it works. I'his works 
not only for simple assignment statements, but kK)p.s and 
conditional siaiemeni.s as well, it is son of ^^programming as 
you go’’ when couf)led with the Terminal's drag and drop 
ability. You can test several lines of code 21 nd if they work 
properly, just drop them in your program. Second, programs 
can be executed from the command line without compiling, 
With Ch 2 icting as a pnjgrum inicrprcter. Many people like this 
opiion for testing out small pieces of code or being able to run 
programs in stages, testing new functions as yr>u build them 
into the program. Tlie i>rtK'ess of liie compile/delmg qrcle can 
l>e skipped altogether. This allows for fast changes to a 
program and tjiiick concept testing. A nice feature of Ch comes 
up when running prognuns this way. IPs error messages are 
not the cryptic type usually given by a compiler when a 
j)rt>gram has problems. When the program fails, Ch prints out 
the offending line and fine nutnlier and also pt)ints to the 
suspected error with arrows. Most of the time, l find this 
feature speeds the proces.s of correcting small enors and 
oversights since you don't liave to pick ilirough a lot of lines 
to find where the problems are hiding. As an example of 
interpretive C, here's the classic "hello world" program run in 
four ways. First is tlie actual program: 

finciutte <5tctio,h> 
int taainU 

r 

printf ( " \tjbel lo vorl d , \n\ 5”}: 


Mati Cainpliell is a Gnttluiue Siudeni in Mechanical Hngineering at University of California, Davis. lie ha.s Ix-ojnie a ilevoied Mac uscrtJvcr tlie past 
2 years and has recently entered tlie w'orld of j-jrograiTiinlng. i !e f>01x^8 that more engineering apps will ix' developed for the Mae st? lie can finally 
convince his colleges that Macs are the way itj go. Feel free u> pn>vide some feedback at mtycarTipbell@ucdavis.ediJ. 
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Matt/s — ch — ch 


Ch 

s 

Professional Hlition, versim 3,7,0.11231 

n 

Cc> Copyri^t 2061-2003 Soft Integration* Inc. 
http ://Wiiw ,sof iinUgrot t on .CO* 

AIsers/lKitty> cd dVeh review/progroiivs 
/Us^s/BOtty/ch/Ch Review/progronis^ helto.c 


hello world. 

i 

/Uaers/jiatty/di/Oi R)(»¥tew/progra«s> 

L 

A 

D 

▼ 


Fi}*ure L Cb shell hello.c as iin Imerpreier 


Figure 1 above show.s the first niethocl, the prograrn Ijeiug run 
by typing the name at the commantl prompt. Ch uses a.s tht^ 
default [>rompl. Along wlili itie (>rogram file, you just need any 
associated header files and library files if you programmed them 
sepamtely. Below are the other ways. In the second, the 
conunand is interpreted directly and executed, 'lliird, ihe same 
thing is done wiifi C++ ccxie. More aix>ut that in the next section, 
the founli way is the simplesr. All that is needed is quotes and 
Ch inieq^rets this as a string. 


Interpreting C txxle on the command liner 

> priiiLf("hello woild."J 
hello world* 


C++ interjHieted: 

> cout << "hello world," << endl 
hello world. 


Interpreting a string dirt^c lly: 

> "hello world" 
heAlo world 

This is another example of code executed on the command line. 
Here \ acuiLilly defined a simple funtaion and then used it as you 
nomially w'oiild inside a prt>gnim. 

> void input(void)[char a[ZO].h[20l jacanf{"%s"pa); 

Gcanf .b) rprintf ("\u%s\n" , Fstreat (a*bl); I 

> itipurO 
Mac 
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In addition, the two methods of interpreting C can be 
combined. Programs can be run from the command line with 
. program.c (that’s a period followed by a space then the 
program name) in the current shell 'fhe functions usetl in the 
program will remain loaded in memory after the program is 
run. Tlien they can by used interactively on the command 
line. This works great for more coniplex funclions that you'd 
like to try out. Class definitions and all the related member 
functions for C4+ code work the same way. All the memi>er 
functions can be tested interactively. By running an empty 
program that includes any necessary header files, all the 
funclions can be tested without having to write a program 
that uses them. 1 like being able to try out functions this way 
to help me visualize program flow. The parse shell command 
is similar. Used for debugging, parse prog ram,c checks for 
syntax error-s anti keeps functions loaded in memory without 
running the program. Variables have to be declared in the 
shell; drag and drop works nicely here. Once created though, 
they can [)c used in function calls just as in a program. 
Return values from functions can even be passed back and 
assigned to variables in tiic shell. 

Ch us not just for simple programs; it can handle larger 
ones. When studying Dynamics recently, I used a program 
called Autolev that symbolically formulated the equaiiuns 
motion of a system of bodies and then wrote a C program 
thin numerically solved the resulting differeniial equations. 
In my particular case, I sought to simulate the .simplified 
kicking motion of a person, Auifdev wTote a program that 
came ion at over a thousand lines, inclutitng the recursive 
numerical functions. Ch ran the program without any 
problems and without the need to go to a compiler. Tlie l)esi 
f)ari was that w'ith only slight modifications, I was able to get 
visual output in the form of graphs by adding just a little bit 
of code, ril have an example of graphing in Ch a little later 
Thi.s was great because not only was the feedback 
immediate, liut it also kept me from having to import my data 
from multiple output files into a spreadsheet every time I ran 
the simulation. 

SuppoRTiN(i C90/C99/C+> Standards 

The ability to run C interpret ively is nice, Add to this the 
fact that Ch is built to completely encompass the C90 
standard, the standard that most C code is based on, and 
you have a good place to develop code, Ch goes [)eyond 
this, adding fitnctionaliiy to C l>y l^ringing in some of the 
newest standards, borrowing ideas from other programming 
languages, and blending in new functions to enhance C. Ch 
adds in many useful features from the new standard for C, 
C99* In keeping up with the limes, Ch support.s complex 
and long long type variables, floating point arithmetic, 
variable length arrays, pt>lymE}rphism for generic functions, 
binary type output for printf statements, and the // comment 


style. Most of the new standards that are .suppoaed in Ch are 
those that help in writing co<le for numerical computing. 
Along this same line, Ch has added some practical features 
from C44. It supports classes with public and private 
members, reference type and pass-by-reference, and the 
cout, cin, and edrr functions to name some of the main ones. 
Thus, object oriented programming is possible without 
having to go completely to the C++ language. As C++ does 
nor necessarily support all the newest features of the C99 
standard, Ch becomes a mixture of the two, combining some 
features of both. The following is a simple program that uses 
classes. Immediately after it, you can see where 1 used the * 
classes.cpp syntax, both running the program and loading 
the classes into memory, I then used tlie class definiiion and 
functions on the command line. 

// test iJM s of class 
tflncJude <iostreatii,h> 

class Triangle 
I 

public: 

Triflnglfitdaubly, double): 
void hypotenuse0: 
private: 

double m. n, "h: 

\i 

itit tnalnU 
t 

class Triangle tl ” Triangle(3, 4): 
t 1 .hypoteruiseO : 

clasg Triangle t2 - TriangletS, 12): 
t2,hypotenuse{): 
return 0: 

I 

Triangle::Trlangle(double a. double b) 
t 

ra • a; 

n ” b: 

I 

void Triangle::hypotenuse(} 
t 

h ® aqrt f fm'm) + {n'n)): 

cout v< ■'Geometry of a Right Triangle" << endlj 
cout « "Sides = " « m « " and " « n « endl: 
cout « "Hypotenuse « " « h (< "\n'' << endl; 

I 

// End of file 

> . claasea.cpp 

Geometry of a Right Triangle 
Sides = 3,0000 and 4.0000 
Hypotenuse = 5,0000 

Geometry of a Right Triangle 
Sides » 5.0000 and 12,0000 
Hypotenuse - 11.0000 

> class Triangle tl ^ Triangle(2* 3) 
y tl.hypotenuse0 

Geoiiietty of a Right Triangle 
Sides = 2.DODO and 3,0000 
Hypotenuse = 3.6056 
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Keep track of every second of your time and bill 
for it with Time Track! Built in instructions make 
it easy to use. It is a simple way to manoge your 
billable time for multiple projects and create a 
web page to show to your clients. Only $24,95 
per single user license per platform. Finollyi A 
versatile time tracking solution for Mocintosh, 
Windows, and Palm! 


www.trinfmity5oftware.C0m 



By TLA Systems 

The Dock with more than one dimension. 

Create multiple docks of any size, assign hot keys and 
even put the Trash back on the Desktop. A flexible and 
feature-laden tool for power-users. Runs natively on Mac 
OS X and 9 in five languages. 

”... you made the iM/dr to OS Jf o hf easier for me,,." - Sob ieWys 

‘'...DragThiag atn righlfuSy be railed an mdkpemabk aid to working with your 
Mac..:-MQrU5erm 

Download a copy now from www.dragthing.com. 




Trapcode - plyg-ins for Adobe® Afler Effecfs® 

Trapcode Shine is a fast light effect plug-in. The effect looks 
very much like volumetric light, but is actually a 2D effect. 
There are special controls to moke shimmering lights and 
numerous coloring modes. This is an effect that you see 
everyday on TV and in many movie titles. Shine is available 
for Mac, Mac OSX and Windows. 


WWW. trapcode. com 


Eudora Internet Mail Server (EIMS) 
3.2 is the latest version of the most 
popular Internet mail server for the 
Macintosh. If you need to handle 
email for o dozen users, or 
thousands of users, EIMS is a 
reliable and easy to use solution, 

EIMS 3.2 is availabb far USS400.0Q, there are no limits ofi the numlwr of users 
ihot con he odded, and free eoitoit su|»pi>rt i$ tMiuded. 

For more inhrtnation, see 

http://wwwieudor0«co«nz/ 


GraphrcConverter converts 
pictures to different 
formats* Also it contains 
many useful features for 
picture manipulation. 

See wwwJemkesoft.cam 

for more information* 
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JNew Data Types 8l Feaitjrils 


Slrinj;_t type 

Ch alw) crimes with new data t>pes and funttions. Strings 
have l'>een proiiuncd to a Urst class object using a new data ty pe, 
siring^t. This type autoimtically handles memoiy alloaition as 
needed, frees used menioiy^ when appropriate, and allows 
strings to be used in symbolic computing. Strings can also be 
u.setl to control the number of iterations in a loop, Aforeach loop 
lias been added, which bieaks a siring into tokens and Rins 
through the kxjp once for each token, as demonstrated lielow. 
This function has a man page within Ch. 

r ITsini? tlie forc:idi kKJp 7 
if i nclude <stdio , h> 

itiL mainO 

f 

string^t loop, token; 

loop “ "this string lias been broken yp": 
foreacbEtoken; loop) 
printf P'%a\n''. token); 
return 0; 

[ 

// End tif file 

> loop.c 

this 

string 

ban 

been 

broken 

up 

As with strings, arrays can be ust^tl in new ways as well. 
Assumed shape arrays, name[:][:], are allowed In function 
calls where ilie shape of the array is nol determined until run 
time. Array subscripts can lie declared explicitly, meaning 
that the first element of an array can l>e element 1 or even - 
1, instead of 0. 

ConiputationaJ Array Type 

Computational arrays have been added as a new data 
type, array type name[m][n], which allows them to be treated as 
a first class object. These can be ihought of as matrices and 
vectors for use in calculations. This is where the numerical 
part of Ch really shines. In C, arrays have to he handled with 
many levels of embedded loops. In Ch, conversely, the 
solution to a matrix equation or printing an array can often be 
done with one line. Outptii staiemems can have matrix 
etjuations as arguments and print them as If they were single 
numbers. Matrix math can be done as .simply as rioaling-poini 
math, Array_1 * Array_2 will perform the matrix multiplication 
according to the rules of linear Algebra, The operator 
niLihiplies corresponding elements of two arrays times one 
another. Generic math functions also work with the new data 
type. 'I’he ft>Ilowing is an example of computational array 
type, how^ it can be passed to functions, and using it for 
computations and output without loops. 

/* niairix eilcLrtatit>ns in Ch */ 

#include <Rrdio.b> 


fHuc^lude <ari:ay.h> 

array double ftinct ion (array double 

array double [:JI:i. t:J : 

Int mainO 
I 

array double AL[3j[2] - tl. 2, 3, 4. 5. 63: 

array double M[2] [^1 “ U. 2, 4, 5); 

array double BL[4l[2] =11. 3, 5. 7. 10, 11, 12. 133; 

array double B2f2]12] = |7, 8. 3, b\i 

int Cl = 1. C2 = S: 

printf {"\iiPart lArAlg", function(Al, Bl, Cl)); 
prititfC\nPart 2:\n%4g". function(A2, B2, C2)): 
return 0: 


array double function(array double a[:][:J. 
^ array double b|t][;]. Int c)[:][:! 

return t * {a ,* a) * transposetb): 
f 

// End of tile 
> maLrlx.r 
Part 1; 

13 33 54 64 

57 157 266 316 
133 377 646 768 

Part 2; 

195 135 

1560 m 


lIerL% similar arrays and functions are inlerpreted on the 
command line: 


> array int x[6] 

> array int ylfl 

> lirtspace(x,1.6) 

6 

> 5 £ 

1 2 3 4 5 6 

> y 

0 0 0 0 0 D 

> void add (array int 'p. array Int 'qjit|=p+p: l 

> void square(array Int array int *t) 

f t=E. *a:printf ('’s=\n%d\nt=\!i%d\n''.s. t] * ] 

> add(x,y) 

) y 

2 4 6 3 10 12 

^ square(x.y) 
s= 

1 2 3 4 5 6 

t” 

J 4 9 16 25 36 


> y 

1 4 9 16 25 36 


New fund ions have been added in Ch to aid in using 
computational arrays, most of which are for numerical 
computing. Hus allows for complex computations to be done 
in C wiihoui going to another math program. UnforRinately, 
Ch does not include the ability to do symbolic manipulations, 
nor does it have the depth of numerical functions thai .some 
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prftfes.sif)nj»! lt‘vc‘l niaUi programs have, hut the most 
imponant computations can be handled numerically. 
Statistics, data analysis, Fourter iransFonns, vccttir algebra, 
integration, and differcniiatiun are just a lew of the 
comptiiaiional algorithms that have been included. They arc 
available in the header file numeric.h. Most of ilic matrix 
manipulations used in Linear Algebra, such as transpose, 
inverse, i)r more complicated ones, can he done as 
demonstrated in the example above. 

Using compinaiional arrays, an array of reference can he 
passed to a function, whicii can handle multiple data typt.^s and 
dilfcTen! dimensions. One function can lie given iiuicli more 
flexibility this way. Functions cim also return compiitatiorud 
arniys of varying dimensions, making It easy to give values [jack 
to the emailing function, ilte shap©() function is a simple way to 
get array climensions when using an array of reference since its 
size is not passed. Shown here with txxh computational and C 
arrays, it returns the dimensions of the argument, I5y using it 
twice, you can get the total number of dimensions. 

> array double afSllGl 

> shape(a) 

5 b 

> shape(£hape(a)J 
2 

> double b[ 2 ai 


> shape(b) 
20 


IVo & Three DiMi'NsioNiVi Plotting 
As a cum[>limeni to the increased numerical 
capabilities, Ch has also added higli level ploiting through 
function calls that look and feel like C. Both 2-D and 3-r> 
plots can be implemented with simple function calls, or 
tliruugh a class designed to handle plotting named CPiot. 
I'he plotting functions, e.g. piotxyz(), will accept all the 
default display o[>tions. The only arguments needed are two 
or three arrays, either computational or C arrays, with the 
correct number o( points. You can add axis labels and a title 
with f>piional inputs. These functions are great for gening 
quick feedback by adding one line of extra code to a 
program. By using the CPIot class, many more options are 
available througli the meml^er functions. Data can be added 
in sets to allow for multiple curves or surfaces. Subplots 
can be generated that oc:cupy the same window but use 
different data sets or are different types of plots. Plotting 
can be done to the screen or directed to a file with a 
specified type. I have fntmd l»NG files to l>e the most useful 
as tliey are read by ITeview, but you can also output a 
postsenjg file if you use an application ihai will read them. 
There's quite a h\i of flexibility given the relatively simple 
commands that are used. Plots can l>e rectangular, polar, 





Who has the host fixed wireless 
seivtien in the industry? 
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cylindrical, or spherical. 2-D ploLs can be simple lines, 
steps, impulses, or points. 3-D surlacus can be drawn as a 
mesh, impulses, or points all with or without contours. The 
view oriemation for 3-D ploLs can be changed. There are 
many more options available for graphs and demos of each 
can l>e found on the Softintegration website. Below, Tve 
created two simple examples of plots done in Ch. Figure 2 
was done on the command line. 


> array double xllOO] 

> array double yllOO] 

> llniipace(x. 0, 2*H_PI] 
100 


> y - sinCx) 
Q.OOOO 0.0634 0. 
0.3717 0.4293 0. 
0.6428 0.6901 0. 
0.S8t5 0.9096 0- 
0.9848 0.9938 0, 
0.9788 0.9638 0, 
0.8660 0.8326 0. 
0,6182 0.5671 0. 
0.3420 0.2817 0. 
-0.0317 -0.0951 
-0.3420 0.4009 

-0.6182 0.6668 
0.8326 0.B660 

-0.9638 -0,9730 
-0.9989 ^0.9938 
-0.9341 -0.9096 
-0.7761 -0,7346 
-0,5406 0,486?. 

-0.2511 0.1893 


1266 0,J393 0,2511 0,3120 
4862 0.5406 0.5929 
7346 0.7761 0.8146 0.B497 
9341 0.9549 0.9718 
9989 0,9999 0,9969 0,9393 
9450 0,9224 0.8960 
7958 0.7557 0.7127 0.6663 
5137 0,4582 0,4009 
2203 0.1580 0.0953 0,0317 
0.1580 -0.2203 0.2817 

0.4582 -0.5137 -0.5671 
-0.712J -0.7557 -0.7958 
-0.8960 -0.9224 -0.9450 
-0.9893 -0.9969 -0.9999 
-0.9848 -0,9718 0.9549 

-0.8815 -0.8497 0.0146 

0.6901 0,6428 -0,5929 

0.4298 -0.3717 -0.3120 
0.1266 ’0,0634 0.0000 


> plotxyix. y. '^Sin(x)\ "X". "Y") 
0 


jMLizi^zz: XCS-P^>t 


Sin(3fJ 



Figure 2. PloUing Sine wave from command line 


Figure 3 iMflow shows the output of die plol,c program. Here 
plotting is done with the CPlot cla.ss. 

r piuLc 7 
r 31) Plotting 7 
tfincluda Cstdlo.h) 
i^inc;ludc <math.b> 

#include <chplut.h> 


# define tJUMPTS 30 
int loainO 

I 

//\^riabks 

array double x[J*UHPTSj. ytl^UHPTSj . al [NLfKPTS*NUMPTSl, 
it2[NUMFTS*NUMPTSj : 
array double levelsl6j; 
int i. j: 

striug_t xlabel “ "x"*. ylabel ” "y"* zlabcl = 
title “ "3D Surfacfifl'^: 
class CPlot plot; 

// Creaie data for x, y,nnd levels arrays 
linspaceCx. 1. 1); 
llnepaceCy. I, 1); 
litspace(levels. -1. 1); 

// Compulation cif 2 ^^urfac<f^ 
ford “ 0: i < miMPTS: 1-H-) 

I 

for(j - 0; j C miMPTS; j++) 

I 

zi(NiiKPTS'i+jJ = xUDxliJ + yfjl‘y[jl - i.o; 
zZlNUMPTSH+jJ - Sint6*xli]) * sin(6‘y[j]): 

1 

1 

// linicr arrays lu dass ’'phrt*' 
plot.datalDCx. y. xl): 
pIot,data3D(x. y. z2]\ 

// Set options for graphing 

plot.changeViewAngle{60. 6031 

plot,contourHode(PLOT CONTOUR BASE); 

plot,contourLevels(levels): 

plot.title(title); 

plot.label(PL0T_AXTS_X. stlabel); 

plot,label(PL0T_AXTS_Y. ylabel); 

plot.labeUPL0T_AXlS„a. zlabel): 

// C^raph resulis 
plot ,plottingO : 

// Create output files for priming 

plot, out put Type (PLOT^tlTPUTTYPE^FlLB, "png color". 
"ploL_flle.piig *): 

plot-plottingO ; 
return 0; 



JCO 


V Ch^t-ta 




Figure .i Tu^o 30 surfaces from program phtx 
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COMMAISD SllliLL & SlUiU PkOGKAMMIMG 

Perhaps the most useful feature of Ch is its ability to run 
as a sheih You interface with Ch on the command line from 
within Terminal or the XU application. It runs just like a 
Unix shell with all the same commands available. It can be 
started from within any of the shells that come with the Mac, 
be it bash, sh, csh, tcsh, or zch. You start il by typing ch at 
a command pronipt. You can also stan these other shells 
from within Ch, if you so desire. While this may mean no 
fancy interface with lots of buttons or menus, it's good news 
for the dcdicaied Unix users who like the fact that they can 
now' wrap their hands around Unix on the Mac. To people 
unfamiliar with a Unix terminal, as I was a year ago, this is 
an opportunity to learn. I mean, who wouldn't want to know 
how to use the vi editoi? You may not end up using the 
terminal as your primary interface for day to day w-ork since 
the Aqua interface is much more human friendly, imt no 
doubt you'll find it useful with the mass of information that's 
out there on the topic of everything Unix. If you end up 
using Ch regularly while running and testing code, you can 
make Ch the default shell used by Terminal, as mentioned 
in the Setup section. No need to run the default tcsh .shell or 
any other shell at all. You can also save a Terminal file that 
runs CIl Just set Ch as the default shell, open a new one, 
and set all your other preferences; then use Terminal's Save 
As command to store this shell for c|uick access from tJie 
library menu. 

The fact that Ch runs as a Unix shell has another 
significant meaning. While Ch will run scripts the same as 
any (Hher shell, the fad that Ch is a C interpreter gives you 
have the ability to include C code in your scripts, Loops and 
conditional statements can use the m{)re familiar C syntax. If 
the first line of the shell program is#!/bin/ch, you don't even 
need to be mnning Ch to be able to execute the script with 
included C code. To compliment this, scripts can be called 
and run directly from inside of a prograin. No special include 
function is necessary, just the script name and path, if it 
happens to be in a different folder. These features will give 
anyone more options wlien il comes to shell programming. 
Not having to learn another syntax for wilting scripts is nice 
too. I'he script below, saved as script!ng.ch, uses C right along 
side some regular shell programming, 

#1/hin/ch 

iflnclude <stdio.b> 

edio Sample acripL 
iijt i; 

fqr(i "0: i < 5; i++) 

printf (■'hello i): 

J 

itit trailsfer (void) I 

echo Kaking copy of file 
cp ./testl.txt ./testl.txt 


echo Copying contents 
transfer 0; 

echo moving new file 
mkdtr ./testfolder 

rav ./teslI.lxL . /1 ea t rol dcr/tcintl. txt 
echo doneE 

int transfer(void) 
t 

FILE 'in. *out: 
diar c; 

ifU{jn " fopen("tef!t2 .txt” , "r''))} 

[ 

perror ("^impflle"^}; 

return -1; 

I 

In = fopenp'test2.txt\"i:''] : 
out ^ fopen{'^test3.txt" . ^a") : 
while((c = fgate(in)} != EOF) 

I 

rputeCe, out); 

1 ; 

echo Closing files 
fclose(in): 
fclosetout); 
return 0: 

// Entl (tf tild 

> scripting 
Sample script 
belio 0 
hello 1 
hello 2 

Making copy of file 
Copying contents 
Closing files 
moving new file 
done i 

Ch adds an additional feature to make running scripts 
and programs even simpler. If the file is named with the 
extension '.ch', it is not necessary lo include ihe extension on 
the command line to run the script. It's automatically 
recognized as shown in the above example. At the prompt 
following the script, just typing ihe filename wiihout I he 
extension is enough to run it. As Ch runs programs 
interpretively, this works the same when running C programs 
too. The drawback here Is ihai if you want to compile a 
program using a C or C++ compiler you wilt get an error 
unless you change the extension to or kepp*. 

Easy interface with Existing C LiBiLutY 

Another nice feature coming out of the faa that Ch supports 
the current C standards is that you can use existing C libraries 
without modification under Ch. All of the existing tools tliat 
youVe developed previously will not need to be rewritten as if 
you are transitioning to a new type of language. By utilizing the 
SDK package for Ch, even precompiled binaries can be included 
within Ch as in C, 

Positive and Negative 

So hir I tried to cover all die features and positive things 
about Ch Chat I've run across in my personal experience 
using the program. To summarize, t like its tight fit with the 
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Mac :ind OS X, Considering that the Ch inierface is basically 
a shell and that the Mac now comes with utilities to provide 
access to Unix, thc 7 seem to complimcni one another I 
believe the power of Ch's interpretive nature will aid anyone 
in shell programming and writing C code. Built on the 
standards of C and expanding on them lo bring more 
potential to the language ensures that it will always be a 
useful tool. Don't forget that the Standard version of Ch Ls 
free for Mac OS X (Linux and Unix loo). Tins alone will 
provide anyone with a simple, clean interface for running C 
and C-‘'+ code. This version doesn't include the 
compuLational array type, added numeric funciionSj or 
plotting, but it's a fantastic way to learn C interactively. Just 
be prepared to learn some shell commands if you've never 
used a Lenninal interface before. 

That being said, there are a few areas where Cli could 
stand some improvement, One of the first things you might 
notice is the lack of a Tab Com})iete feature ai ihe command 
line interface. This is a handy diing to have when navigating 
the command line. In Ch, long file names, which 1 am a fan 
of, have to he typed out completely. Dragging and dropping 
files from the Finder to the lenninal window can save yesu 
some of this work because thLs includes the entire path, 
Lnlike Unix, thankfully, Ch is not case sensitive and can 
handle spaces without qutJles or backslashes when it comes 
to file and folders names. This makes it a little easier to 
navigate through the folders that might give you longer 
names when using Ac|ua. Still, Tab (Mmpick* i.s sr>rely missed 
when in a Ch shell Another issue crops up with file 
permissi{)n.s. When a new file is created with vi or another 
text editor, it is not set tcj be an execiitable file so Ch will not 
run it. This might be an inherent feature of Unix for securiiy 
reasons. You need to modify your file with chmod 755 
fllenamex. This will make it exeaiiable to everyone. Ch will 
then run the file as I have in the above examples. 

There is a lot of documentation that comes with Ch in 
the form of PDF files located in /usr/local/ch/docs. The Ch 
Users Guide is almost 700 pages and covers not just Ch l)ut 
much of the C language in general and many Unix 
commands. All hough very thorough, IPs a plain, utilitarian 
document .so, as with most manuals, it is not always easy to 
read, ti does have a lot of useful informiuion .such as the 
summary of the most common shell and vi commands and 
comparisons betw'een Ch and other languages. The Ch 
Reference Guide is close to 1000 pages and gives detailed 
information on many C and Ch functions found in the most 
common header files. Those with ejuite a hit of programming 
experience can probably sift through these docujnents and 
ptill out the stuff they need quickly. Beginners might w^ant a 
differem hook to show them the basics of C. 

PcTha[>s the biggest disappointment with Ch for the Mac 
is the lack of any kind of copy/paste ability when it comes 
to graphing. As shown above, graplis are drawn inside new 
windows in Xi U You can't copy or drag the graph from here. 


Screenshots seem impractical unless you use a .slick screen 
capture program in lieu of Grab. 1 typically save graplis as 
PNG files from within the program and open them in 
Preview, Thi.s works well given all of Preview’s export 
options, but it is still frustniting not being able to simply drag 
and drop the graph right from the window^ tmto a document 
or copy and open it directly in Preview from the pasteboard. 
As this Is a limitation of Unix and not Ch, it will not be 
changing anytime soon. It will only be another reminder of 
why we like the Mac interface .so much. On the topic of 
graphing, Ch needs X windows in order to display graphs. 
I he Ch website lists XfreeS6 (XDarwin) with the OroborOSX 
window' manager as .system requirements. 1 have been using 
Apple’s XM (Beta 3) without any problems. The catch here 
is if yon like u.sing lerminaFs more user friendly interface as 
opposed to the xLerm in Xtl, yon need to .start the Terininal 
application from within XIi, either llirougli the Application 
menu t)f by modifying the -/.xinitre file. 1 actually learned 
how^ to do this in the "XI1 Tweaks" article in the May 2003 
issue of McicTecb, 

There's quite a bit of infomiation here, but as this can’t 
really cover it all effectively, 1 would urge anyone who's found 
this interesting to dieck out Stjl’isniegralion's website. Aside from 
more information, example code is abunckuit. lliere is a Sludenl 
version available and also a 30 day Demo for the Professional 
version. Scripting and numerical computing are definite strong 
points, but there are many other features to check out. Ch has 
to be tlie best and nio.si intuitive way to learn the C language. 
Considering you can gel a free simple tool lo u.se ihe latest C 
standards inteqiietively, it's tlefinitely worth a look, 
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POSTSCRIPT 

Ch 4.0 was recently released. Staiting wath this version, Ch 
Siandiird Edition is freely available to everyone on all supported 
platfomis. The I’rol'essional Edilicju is now J'rce to all aeadenik' 
users for all platforms, giving them access to the computationa] 
and graphing feature.s. 
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BOOK REVIEWS 


By Vicki Broum. 

What’s on Your Bookshelf? 


Ten for X 


BlUDINCi A LmRARY 

Macintosh users kwe, nxiditionally, prided tliemsclves on 
the fact that they don't need to read manuals. While users of 
""iftose otiicr ofKtraiing sysiems” ran'i get by wiihour “cracking 
the hooks”, Mac users smile and flaunt llic fact tiiat the booklet 
that came in the lx>x is still in its original shrink wrap. That’s oui- 
iradiiionah public face. 

In private, however, many Mac OS users actually do coliect, 
read, write, and refer tt) lxK>ks, We want to understand this 
operating system that we use daily. We wfant to know more 
alniut its intricacies and jdkxsyncrasies. We want to learn new 
tips and tricks that w^e c-an use to impress our friends. On the 
down side, Apple doesn’t really supply a manual with Mac OS 
X. On the plus side, there are several publishers (and quite a few 
excellent writers) producing plenty of books on the subject. 

Gktting Starit-d 

[n 2(X)2, the first edition oi Mac OS X: 7he Missing Manual 
was the number one bestselling eoniputer hook. Created by 
David Pogue, computer columnist for 'Itie New' York l imes and 
bestselling Macintosh autlKjr, the “Missing ManuaT series lays 
claim to providing the books “that should have l)eeii in the lx)x” 
and lives up to its claim. 

At 712 pages, Mac OS X: 7t?c ML^sing Mamuil is a sturdy 
tome, covering the Desktop, lander, applications, conif^onents, 
the Unix underpinnings, and much more, hven Mac OS X pow'er 
users should consider owming a eot>y of this IxKjk. At the very^ 
least, you 11 want to retxaiimend it to all of your friends and 
relatives who are still using Mac OS 9, as a gentle introduction 
to the w'oriders of Mac OS X. 

A more advanced botjk, Mac OS X Unleashed (John Ray 
and William C* Ray), is aimed directly at power users and 
administrators. This book also srans by covering the basics, 
such as the rinder and applications; then it moves into the 
deeper administration arcana of networking, adding users, 
using the Terminal applicaikm, and the Unix command line. 
In fact, inucli of the book concentrates on capabilities that can 
be reached from the command line, rather than the Finder, 
and there are more textual examples than piettires throughout 
the book- 


If youVe a power u.sct or administrator (c)r seek to become 
one), you II want a copy of this book. My only gripe with it is 
that, at 1520 ]>ages, it’.s more thari a little awkwaid to handle! 

If ycsu're already ai an advanced .stage, but want a handy 
reference Ixfok, try Mac OS X in a Nulshell (Jason McIntosh, et. 
aL) Part of the O’Reilly Nutshell series, this Ix^ok provides a more 
teixe reference than the two mentioned above; Nutshell books 
“give you wiiai you need to know in as few words as possible'*. 
Ibis i.s the bcK)k yoifll want to consult when you already 
understand the basics of what you need to do, but cannot quite 
recall the specifics. Ii also provides a handy w^ay to review what 
you know, to make sure you liaven’t missed anything major 
And, lest you worry that Terse” equates to less information - do 
not fear. At 800 pages, this lx)ok lias pleniy of "tiuid factor". 

*Nix Under the Covers 

Much has been made t>f the fact ihai Mac OS X is built on 
top of Darwin, a version of Unix based on BSD and the Macli 
microkernel. Although it is poasible to use Mac OS X witliout 
ever making the acfjuaintance of the Darwin layer, power users, 
administrators, and developers (as well as Unix-users switching 
to Mac 08 X!) will want to know' mt^re about Danvin. Tfieie are 
several lK>oks that provide assistance in this regard. 

Two Ixxjks from O'Reilly, Leaming Unix for Mac OS X 
(Dave Taylor and Brian Jepson), and Mac OS X for Unix Geeks 
(Brian Jepson and Ernest E. Rothman), should certainly on 
your shelf. Both are recommended liy the .Apple Developer 
Connection (ADC). Learning Unix for Mac OSK is aimed at Mac 
OS users who are interested in lc*arning abcuit Unix; Mac OS X 
for Unix Geeks is airued at long-time Unix users who are 
“switching” to Mac OS X. Whichever group you see yourself in, 
I'd rec!ommend adding both books to yoitr shelf - if one doesn’t 
address your questions, tlie other probably wall. 

If you want more dejith than these two hooks provide, take 
another look at Mac OS X Unleashed. \ was surprised at the 
amount of content this b<K>k provided on using the Netinfo 
Manager, using Terminal.app and basic Unix commands, and 
more. I’here are chapters on advanced shell concepts and 
commands, shell scripting, server and netw^ork administration, 
and much more. Consider this a heavy duty (in more ways than 
one :-) book for advanced Mac OS X use. 
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Tips, Tricks, and Hacks 

Admit it; one of the coolest things Ix^ing ;i Mac OS X 
power user is the ability to amaze your friends and relatives with 
all kinds of nifty Lips, shortcuLs, and “how did you know tliat?!” 
tricks. If you agree, youll he happy to know tliat at least three 
lxx>ks were WTttten especially for you. 

Mac OS XKiiier Tips (Scott Kelby), deserves a place on your 
coffee table, if only for its look arid feel. Every j>age is in full 
color, with screen shots. You'll find yourself flipping tlirough tltis 
b<K>k simply because ifs fun to do so and youll learn new iricks 
at tile same lime. 

Kelby says weYe all drawn to the little “sidebar" tips in good 
books, because that's where the “really amazing, really fun, 
really useful stuff is htund''. So lie decided to w^itc a Ixjok tliat 
contained nothing but sidebar tips - 260 pages, 2 tips to a page. 
If you don't buy this book for the lips, buy tl iVsr the graphics; 
il’s simply a fun Ixxik. 

Mac OS X Hints, Jaguar Iiciition (Hob Griffiths) provides 560 
tips on everything from the Desktop and Finder to tJnkixle, to 
popular third party applications. For those interested in the Unix 
command line, the book devotes two chapters (and 100 page.s) 
to the terminal, shell, and other Unix hints. 

A more technical set of tricks can l)e found in Mac OS X 
Hacks by Rael Dornfest atid Kevin I lemenw'ay. Davit! Pogue, in 
the book’s Foreworti. writes: 

This l:>ook might cKcasionally lie over the head of 
many Mac fans. (If you want more general, Ies.s 
technical, everyday operating tips, try Mac OS X 
Hints, Jaguar EdiHofi.) 

But some people get as much a kick out of putting 
a compuier through ils paces as tliey do from 
everyday issues like productivity. Part of tiie spirit of 
hacking is doing things that the product’s developer 
didn't c[uiie imagine, finding I he new and creative 
uses diat are only possiliie to those wiio are willing 
to leave the beaten path. For the hackers among us, 
it's all alx>ut The thrill of discovery. 

If that describes you, youll want this Ixiok on your shelf. 

Uh on.., 

SoEuetimes, despite all your precautions or learning, things 
go wrong. Ouch. Or, better, you may want [o fin<l ways to 
l^rcwnt things from going wrong. For tliose times, here are tw^o 
more ixKrks you may want to have on hand. 

Mac OS X Disaster Relief (Ted Landau) is the hook you 
hope you’ll never need. Landau is the founder of the MacFLxit 
Web site (ww'w.macfixit.coni), the “primary first-aid station for 
Mac users in trouble”. In this book, he makes his trouble¬ 
shooting knowledge available to Mac OS X users, covering 
freezes and crashes (both prevention and recovery), third- 
party troubleshtxrfing utilities, installing (and reinstalling) Mac 
OS X, printing problems, and mi ire. If you have never had a 


problem with Mac OS X, consider yourself blessed. However, 
you might .still want a c:f>py of thi.s book cm your shelf, as a 
good luck charm. 

Mac OS X Maximum Security (John Ray and William C. Ray) 
provides “a liacker's guide to protecting your Mac: 0,S X 
workstation and server”. (Note: Tlie media notwithstanding, 
hackers are tlte good guys; crackers are the bad guys.) 

Ibe original Mac OS (long before Apple called it “Mac OS”) 
didn't need much security. As this hxiok's authors pul it, from a 
security standpoint, ifie early Macs might as well have been 
toaster ovens. *l'hey couldn't be compromised because, like 
toaster ovens, there was nothing to c ompromise. In recent years, 
however, the Mac OS has matured; the good news is that users 
have more and Ix^rter features; the bad news is that security, 
once a no-brainer, has become an issue to consider. 

Security is all alxjul knowledge, risk assessment, and trust. 
Tile autiiors provide an introduction to the concepts and 
philosophy of computer secLirity, including physical acce,ss, use 
policies, people, and limitations. The first nine chapters will 
give you a firm giounding in the theory and concepts of 
security (and how security can lx? compromised). C!hapters 10 
through 16 discuss specific Mac OS X resources and how to 
secure them, providing lips, tricks, and recipes. Chapters 17 
through 20 concentrate on prevention, detection and reaction to 
attacks. If youVe a system a<.lministrator, or you’re htx)king your 
Macintcish to the Internet, you may want to read this book... 
before you need it. 
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Qt/Mac, the Mac OS X version of the Qt ■ integration with Project Builder, allow- 

multiplatform C++ application framework, ing developers to use Apple’s own IDE 

provides a uniquely unftiir technological for editing, compiling and debugging 

advantage in software development. Qt/Mac Qt/Mac applications 

lets Mac developers develop in C++ on the ■ OpenGL support, for sophisticated 3D 

platform they love most, while targeting TROLLTECH"* graphics on the Mac 

additional operating systems, such as g ^ as the Aqua style 

Windows or Linux. Qt/Mac also offers: ■ , i r • w • 

Don t take our word tor it. Visit us at 

I lly o ject-oriente , e egant www.troUtech.com/mac.Lookatourlistof 

H single-source, multiplatform development solution Fortune 500 customers. Read what programmers 
I native compiling and applications that run at say about Qt. Download the evaluation version, 

native speed and see how easy C++ development can be. 

Qt/MAC:THE UNFAIR ADVANTAGE IN C++ DEVELOPMENT 
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Revolution 2.0: the English like language designed around the way you think. ^ 
g’;; ■ Develop and deliver on Mac OS X, Windows and Linux m 

- (not to mention 10 other platforms). ^ ^ 

Take the English language, add elegant KMU more SQL databases than you care to learn, 
intrinsic video capture, Unicode, CGI scripting,sophisticated Reports, and build your solution faster than anyone efSe. 
Jaguar, Panther, XP? Revolution lets you eat platforms for breakfast. And speaking of eating, our Cookbook of examples 
gets you up, running, and productive NOW.You can join the Revolution for as little as $99... I ; 

Build with it, deiiver with it, iove it - and still have time for vacations. 

And fora limited time, your MacTech special lets you get 100% of the Revolution for 15% off- 
go to special.runrev.com NOW. Thousands of developers have already Joined. 

OonT iet the Revolution in modern coding start without you... 


Software At The Speed Of Thought 
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